Skip to content

Developer Guide

Jump to bottom
appatalks edited this page Aug 13, 2026 · 1 revision

Developer Guide

This page is for contributors, source-build users, and maintainers. Eva is a framework-free web UI packaged in Electron with a Python bridge for AIG, memory, ACP, local MCP, and workspace services.

Source Build

Prerequisites:

  • Node.js 24 or later
  • Python 3.12 or later
  • GitHub Copilot CLI authenticated locally for ACP-backed functionality
git clone https://github.com/appatalks/eva-agent.git
cd eva-agent
./install.sh
cd standalone
npm install
npm run dist

For a development build with Coding Workspaces enabled:

cd standalone
npm run start:workspace

The Linux AppImage package is built with npm run dist. For Windows packaging, run npm run dist:win from a Windows checkout. The Windows path is experimental; Linux-specific desktop automation and camera discovery are not available there.

Project Map

Area Ownership
index.html, core/style.css, core/js/ Framework-free browser/Electron renderer and feature modules
core/js/options.js Shared UI behavior, settings, config persistence, and model routing
core/js/aig.js, cognition.js AIG orchestration and optional review/action handling
tools/acp_bridge.py, tools/bridge/ Loopback bridge, ACP, memory, skills, MCP, workspaces, telemetry, and background work
standalone/ Electron main process, preload boundary, packaging, and terminal broker
tools/tests/ Curated validation scripts
tools/eval/ Behavioral evaluation harness

Architecture

Browser / Electron renderer
  -> provider modules or loopback ACP bridge
  -> Copilot CLI (ACP), direct provider APIs, or LM Studio
  -> memory, MCP tools, Skills, workspaces, optional automation

The Electron main process owns privileged operations such as bridge startup, workspace capability tokens, PTYs, project selection, and opening local files. Preload exposes a narrow allowlisted API. The renderer does not receive arbitrary Node, filesystem, terminal-root, or workspace-path access.

Key Development Principles

  • Keep the UI minimal and framework-free.
  • Preserve the provider routing boundary; add models to the selector and route them through the appropriate existing send function.
  • Keep transient chat UI state local and do not introduce a server unless the requested feature needs the bridge.
  • Never commit API keys, PATs, browser profiles, runtime databases, token caches, logs, generated audio, or private workspace data.
  • Make narrow, testable changes. Do not use test code as product architecture.
  • Treat external tool output, Skills, memory, and retrieved content as untrusted data.

Useful Validation Commands

Run commands from the repository root:

python3 tools/tests/test_static.py
python3 tools/tests/test_skills_e2e.py
python3 tools/tests/test_workspaces.py
python3 tools/tests/test_workspaces_e2e.py
node tools/tests/test_terminal_broker.js
node tools/tests/test_workspace_projection.js

For packaged UI workflows, use the focused Electron end-to-end scripts:

node tools/tests/test_terminal_e2e.js
node tools/tests/test_workspace_electron_e2e.js

Use tools/eval/run.py --mode mock for synthetic behavioral evaluation. Live bridge tests require an intentionally configured local environment and should not replace focused static or contract tests.

Standalone Runtime and Installation

On Linux, ~/.eva holds installed rebuildable source and ~/.config/eva-standalone holds mutable runtime state by default. Use EVA_CONFIG_DIR to relocate the latter. Installation preserves runtime state and avoids syncing secret-bearing configuration files into the installed source.

An AppImage rebuild keeps the current build and one rollback artifact, refreshes the launcher to the exact new artifact, and removes older AppImages. The bundled AppImage has its own tools/ copy, so rebuilding is necessary before a change in the source tools/ directory reaches the manual-test application.

Contributing

Open an issue for defects or feature discussion, then submit a focused pull request. Explain the user-visible behavior, verification performed, and any remaining risk. For implementation-specific detail, consult the repository's technical documentation.

For end-user configuration and feature use, return to Home.

Eva AI Assistant is MIT licensed. This wiki documents the current standalone application and its optional integrations. Configuration values, credentials, workspace content, and generated artifacts remain local unless you choose to send them to a configured provider or service.

Eva Documentation

Start

Configure

Use Eva

Help and Build

Clone this wiki locally