The Problem

Eigent functions as a portfolio of seven semi-independent projects sharing a workspace rather than a unified codebase. This architecture creates integration friction: the backend (Python/pyproject.toml) and frontend (Node/package.json) operate with separate dependency management, the import graph contains five circular dependencies across 386 resolved files, and critical secrets reside in a tracked .env.development file that .gitignore explicitly excludes. Teams attempting to modify workflow logic face high-blast-radius changes in utils/__init__.py (45 dependent modules) and outsized store files (src/store/chatStore.ts at 2213 lines) that ripple widely with minimal edits.

What This Does

Eigent comprises seven distinct projects under one repository root: package (887 files, React/TypeScript infrastructure), src (287 files, main application code), backend (93 files, Python FastAPI service), server (87 files, Docker-configured API server), electron (15 files, desktop runtime), resources (3 files, media assets), and utils (2 files, shared utilities). The backend runs as a FastAPI service defined in backend/app/service/task.py (19 functions, 33 types, called from 20 other files) which manages put_queue and get_queue operations that persist to the database via SQLAlchemy sessions. The backend/app/component/environment.py (12 functions) controls environment path configuration that 17 other files import, defining set_user_env_path, get_current_env_path, and env functions that mediate model execution contexts. The import graph reveals utils/__init__.py as the single highest-dependency hub (Ca=45, Ce=0), meaning changes there propagate across nearly half the codebase. Five modules participate in circular import cycles involving src/store/chatStore.ts, src/store/projectStore.ts, and electron/main/init.ts, creating startup-order sensitivities. Execution originates from backend/main.py entry points signal_handler (reaches 5 functions) and sync_cleanup (reaches 1 function), or from the start function in backend/app/controller/task_controller.py:28 (reaches 7 functions itself called from 4 places). The system touches the filesystem via 31 functions, a database via 52 functions, performs 4 cryptographic operations, runs 1 external command, and makes 36 outbound network calls—shortest paths from entry points reach database writes through put_queue -> put in under 3 hops.

How It Is Wired

Control flows from backend/main.py through three primary entry points: signal_handler (registered for process signals, reaches cleanup_resources and 4 other functions), sync_cleanup (reaches pid_file.unlink filesystem operation), and start (in task_controller.py:28, orchestrates put_queue -> put database writes). The most-called functions in the internal call graph are put_queue (36 call sites), get_task_lock (35 call sites), and Chat (30 call sites). A representative edge shows step_solve -> sse_json invoked 39 times, and __init__ -> env called 31 times. The backend/app/controller/tool_controller.py (13 functions) performs the widest effect: it defines install_tool which performs cryptographic/secret-generating operations, runs external commands, and reads/writes both files and the database. The src/store/chatStore.ts and src/store/projectStore.ts files each contain 2213 lines of code—the oversized store modules contributing to cognitive load and participating in import cycles. Duplicated code blocks appear across 111 files with 609 repeated 6-line patterns, primarily in backend/app/component/babel.py and server/app/component/babel.py copies. The src/i18n/locales/index module (Ca=1, Ce=11, instability=0.92) represents a fragile localization single point; 11 importing modules depend on stable i18n output. The electron/main/index.ts (Ca=0, Ce=10, instability=1) is a sink with no importers but imports 10 modules, making it a deployment boundary rather than a computation hub.

How To Use It

Setup: The repository requires two separate dependency installations. From the root, npm install (per package.json) installs the React/TypeScript frontend dependencies, while cd backend && pip install -e . (per backend/pyproject.toml) installs the Python service. A Dockerfile in server/ confirms containerized deployment is supported, using ghcr.io/astral-sh/uv:python3.12-bookworm-slim as the base image.

Configuration: The server/.env.example file documents required environment variables, but a server/.env.development file is currently tracked in git despite .gitignore excluding it—a critical concern given the code health audit flagged this as a high-secretion risk. The server/docker-compose.yml and server/docker-compose.dev.yml orchestrate the full stack (backend, database, and any required services) for local development. The package/@stackframe/react/package.json and package/@stackframe/stack-shared/package.json manage the frontend component libraries.

Running it: To start the local development environment, the README recommends npm run dev after installation, which launches the Electron desktop application connected to the local backend. For fully standalone operation without cloud dependencies, the server/README_EN.md provides the "Full Local Deployment Guide" which configures local model integration (vLLM, Ollama, LM Studio) and complete isolation from external services. The CLI entry point is backend/cli.py, and the main Python service starts via backend/main.py.

Real-World Use

A knowledge-worker wanting to automate a multi-step research workflow would configure the system via backend/app/service/task.py to define agent tasks, then invoke start from the task controller to dispatch agents through the workforce coordination layer. The backend/app/controller/chat_controller.py (post, improve, supplement, stop functions) manages conversational agent lifecycle, while backend/app/service/chat_service.py (format_task_context, collect_previous_task_context, build_conversation_context) prepares the context that agents receive. The backend/app/controller/tool_controller.py (install_tool, list_available_tools, cancel_oauth, uninstall_tool) handles tool management—including cryptographic operations for OAuth and external command execution for tool installation. A practical workflow might: (1) define a task in the task store, (2) trigger start, (3) have agents execute via Chat calls, (4) utilize tool_controller.install_tool to add capabilities, and (5) persist results through the database writes that put_queue facilitates. The entire path from task initiation to database commit traverses fewer than 5 function calls across the internal call graph.

Code Health & Issues

The static analysis produced 142 measured findings across 6 categories, plus 12 code health audit findings ranked by severity:

  • [HIGH] Untrack the file your own .gitignore says to ignore - .env.development is tracked although .gitignore excludes it; credentials in this file are the ones actually in use
  • [HIGH] Pin third-party GitHub Actions to a commit SHA - .github/workflows uses @vN soft version pins on softprops/action-gh-release@v1, dorny/paths-filter@v3
  • [HIGH] Pin third-party GitHub Actions to a commit SHA - same as above (appears to be duplicated finding)
  • [HIGH] Commit a lockfile beside the manifest - package.json has no lockfile; unlocked ranges mean tested and shipped artifacts can differ
  • [HIGH] Remove the committed .env and rotate what it holds - .env.development is the most common route for working keys to reach public clones
  • [HIGH] Remove the committed .env and rotate what it holds - same as above (duplicated finding)
  • [MEDIUM] Pin the container base image by digest - server/Dockerfile uses ghcr.io/astral-sh/uv:python3.12-bookworm-slim without digest
  • [MEDIUM] Gate pull requests on a dependency vulnerability scan - no dependency scan in GitHub Actions CI
  • [MEDIUM] Add a pre-commit secret gate - no repo-level gate; a secret-shaped file is tracked
  • [MEDIUM] Move large binaries to Git LFS - src/assets/dynamic_workforce.mp4 (14.3MB), add_worker.mp4 (7.4MB)
  • [MEDIUM] Remove generated build output from version control - 884 generated files committed in build
  • [MEDIUM] Set persist-credentials: false on checkout - .github/workflows/build-view.yml keeps the token

Beyond the measured findings: the repository contains committed secrets (.env.development), no dependency lockfile, and 884 generated build files committed to version control—each representing a vector for credential leakage or version mismatch.

The Bottom Line

Eigent is a capable AI workforce desktop with a clean local-deployment path and solid separation between backend Python service and React frontend, but its architecture as seven semi-independent projects creates meaningful integration overhead. The tracked .env.development file, missing dependency lockfile, and pinned-GitHub-Actions vulnerability are immediate production risks that should be addressed before any team-wide adoption. Teams comfortable with managing separate Python/Node dependency sets and who need local-only AI agent execution will find value here; organizations requiring out-of-the-box stability or zero-configuration setup may find the circular imports, outsized store files, and security hygiene gaps too demanding. The codebase shows genuine technical ambition but requires cleanup of the listed hygiene issues before it's production-ready at scale.