How aegisaifoundation/aegis works
1. What this repo actually contains
- The codebase is currently a Node/TypeScript CLI + terminal UI application called AEGIS Core.
- The README describes a much larger federated medical AI vision, but the checked-in code here is the local control plane: startup, configuration, terminal UX, agent scaffolding, and tool abstractions.
2. Top-level execution path
- The runtime entrypoint is aegis-core/bin/aegis.js, which boots the compiled app from aegis-core/dist.
- Source lives under aegis-core/src, and the compiled JavaScript is committed in aegis-core/dist, so the repo supports both source development and packaged execution.
3. CLI and command boundary
- src/commands/index.ts is the command routing layer behind the CLI verbs mentioned in the README: launch/start/configure/uninstall.
- This layer is the first policy boundary: it decides whether the user can enter the TUI, whether local configuration exists, and which setup or cleanup action to run.
4. Terminal UI subsystem
- src/terminal/App.tsx and src/terminal/Dashboard.tsx form the interactive terminal experience.
- art.ts provides branding/ASCII art for the TUI.
- This layer is presentation-only and sits above the core agent/tool logic; it likely renders status, identity, and operational state rather than performing the work itself.
5. Agent orchestration layer
- src/agent/index.ts is the main orchestration module for the “agent” concept.
- Based on the README and surrounding modules, this layer owns the current runtime persona/role and coordinates actions between the terminal UI, memory, and tools.
6. Tooling subsystem
- src/tools/ contains the capability boundary:
- FileTool.ts for filesystem access
- SystemTool.ts for environment/system actions
- MemoryTool.ts for persistence and retrieval of local state
- TerminalTool.ts for interacting with the TUI/terminal context
- src/tools/index.ts likely aggregates and exports these tools for the agent layer.
- In architecture terms, the agent does not directly do everything; it delegates through these tools.
7. Local state and memory
- src/memory/index.ts is the local memory subsystem.
- The repository also includes .memory/default.json, which looks like a seeded/default state file.
- This is the persistent knowledge layer for the CLI experience, separate from user configuration and separate from runtime process memory.
8. Configuration and identity
- src/config/index.ts manages local configuration, and the README states the CLI stores installation state in ~/.aegis/config.json.
- This is where agent identity and role are configured before the TUI can launch.
- Configuration is therefore a prerequisite for runtime, not just a convenience setting.
9. Shared data model layer
- src/models/index.ts holds shared types or domain models used across agent, tools, config, and memory.
- This keeps the other subsystems loosely coupled and is the likely boundary for common request/state schemas.
10. Runtime and build model
- The project is TypeScript-based (src/*.ts, src/*.tsx) and targets Node.js.
- tsconfig.json, package.json, and the generated dist/ directory show a standard compile step from TypeScript to distributable CommonJS/JS output.
- The presence of node_modules/ and package-lock.json indicates npm-managed dependencies.
11. Installer and launch scripts
- scripts/install.sh, scripts/start.sh, and scripts/dev.sh suggest three operational modes: install/setup, run, and development.
- install.ps1 supports Windows installation.
- These scripts are the external entry surfaces around the core Node runtime.
12. Project structure and non-runtime artifacts
- scratch/ contains experiments and generated assets; it is not part of the main application flow.
- assets/ provides branding imagery used by the README and likely the CLI/TUI presentation.
- .env in aegis-core/ suggests environment-variable-based local configuration, but it is not the primary persisted state.
13. How data flows through the app
- User launches the CLI → command router resolves the action → config/installation state is checked → agent is initialized → terminal UI renders the dashboard → tools read/write local system, file, and memory state as needed.
- The key architecture boundary is that UI, orchestration, and capabilities are separated, with persistent state split between config and memory.
14. How to diagram this repo accurately
- Draw it as a single local Node/TypeScript application with four main internal zones:
- CLI/bootstrap
- terminal UI
- agent orchestration
- tool + state layer
- Keep the federated/blockchain/medical-network concepts from the README as the intended product vision, but do not diagram them as implemented runtime subsystems unless additional source files are added later.
Main entry points: models/index.ts Shared Models · commands/index.ts Command Router · tools/index.ts Tool Hub · App.tsx Terminal App
Components 18
CLI Runtime
Bootstrap and command routing for the Node/TypeScript application.
- Boot Loader · Node entry script that starts the compiled application.
aegis-core/bin/aegis.js - App Entry · Top-level TypeScript application entrypoint.
aegis-core/src/index.tsx - Command Router · Routes CLI verbs into launch, config, and cleanup flows.
aegis-core/src/commands/index.ts
Terminal UI
Interactive terminal presentation and branding.
- Terminal App · Main interactive terminal application shell.
aegis-core/src/terminal/App.tsx - Dashboard · Primary terminal dashboard view.
aegis-core/src/terminal/Dashboard.tsx - Branding Art · ASCII art and branding used by the terminal UI.
aegis-core/src/terminal/art.ts
Agent Layer
Agent orchestration and shared domain models.
- Agent Core · Coordinates agent state, UI, memory, and tools.
aegis-core/src/agent/index.ts - Shared Models · Common types and data contracts shared across subsystems.
aegis-core/src/models/index.ts
Tooling
Delegated capabilities used by the agent.
- Tool Hub · Aggregates and exports the agent capability tools.
aegis-core/src/tools/index.ts - File Tool · Filesystem access and file operations.
aegis-core/src/tools/FileTool.ts - System Tool · Environment and system-level actions.
aegis-core/src/tools/SystemTool.ts - Memory Tool · Reads and writes persistent local memory state.
aegis-core/src/tools/MemoryTool.ts - Terminal Tool · Terminal interaction support for the agent.
aegis-core/src/tools/TerminalTool.ts
State
Configuration and persistent local memory.
- Local Memory · Persistent local memory subsystem.
aegis-core/src/memory/index.ts - Seed Memory · Default seeded memory content for local state.
.memory/default.json - Config Store · Local configuration and installation state.
aegis-core/src/config/index.ts
Launchers
Shell and installer entrypoints around the app.
- Start Script · Shell wrapper for running the application.
aegis-core/scripts/start.sh - Install Script · Shell wrapper for installation and setup.
aegis-core/scripts/install.sh
Connections 25
- Boot Loader → App Entry: starts · Bootstrap hands off into the application entrypoint.
- App Entry → Command Router: routes · App entry delegates CLI verbs to the command router.
- Command Router → Config Store: checks · Commands verify installation and configuration state.
- Command Router → Terminal App: launches · Launch/start flows enter the terminal application.
- Command Router → Start Script: wraps · Start flows are exposed through shell launcher scripts.
- Command Router → Install Script: wraps · Setup and installation are exposed through shell scripts.
- Terminal App → Dashboard: renders · The terminal app presents the dashboard view.
- Terminal App → Branding Art: brands · The UI includes ASCII branding and identity art.
- Terminal App → Agent Core: hosts · The UI drives and displays the agent runtime.
- Agent Core → Shared Models: uses · Agent logic relies on shared domain models.
- Agent Core → Tool Hub: delegates · The agent delegates actions through the tool boundary.
- Agent Core → Local Memory: persists · Agent orchestration reads and updates local memory.
- Config Store → Shared Models: types · Configuration shares the common data model layer.
- Tool Hub → File Tool: exports · Tool registry exposes filesystem capability.
- Tool Hub → System Tool: exports · Tool registry exposes system capability.
- Tool Hub → Memory Tool: exports · Tool registry exposes memory capability.
- Tool Hub → Terminal Tool: exports · Tool registry exposes terminal capability.
- Memory Tool → Local Memory: stores · Memory tool reads and writes persistent state.
- Local Memory → Seed Memory: seeds · Local memory is initialized from seeded defaults.
- File Tool → Shared Models: uses · Tools share common request and result shapes.
- System Tool → Shared Models: uses · Tools share common request and result shapes.
- Memory Tool → Shared Models: uses · Tools share common request and result shapes.
- Terminal Tool → Shared Models: uses · Tools share common request and result shapes.
- Config Store → Agent Core: initializes · Configuration is a prerequisite for agent startup.
- Config Store → Terminal App: gates · Configuration state gates the terminal experience.