How milodule3-debug/aura-code works
1. What this repo is
- Aura Code is a TypeScript autonomous coding agent. The runtime is a Node.js CLI/service that reads a project, decides on a strategy, edits files, runs tools/tests, and verifies results. The README’s modes reflect the top-level architecture: normal loop, multi-agent orchestration, architecture planning, verification, and failure analysis.
2. Primary entrypoints
- The main execution surfaces are src/cli, src/server, and src/workflows.
- src/cli/index.ts is the user-facing command entrypoint.
- src/server/index.ts and src/server/session.ts suggest a server/session layer for longer-lived interactions.
- src/workflows/engine.ts is the coordination layer for task execution flows.
3. Core control loop
- src/agent contains the low-level agent lifecycle: context building, spawning, session persistence, system prompt definition, and the loop that repeatedly plans and acts.
- This is the “single agent” execution path: gather context, prompt the model, invoke tools, capture results, and iterate.
4. Multi-agent orchestration boundary
- src/orchestration is the higher-level coordination system. It appears to route work across specialist roles, manage competences, build plans, and execute those plans.
- The presence of router/orchestrator/specialists/prompts/types indicates a structured split between decision-making and execution.
- This layer is where “Researcher → Coder → Reviewer” style flows likely live.
5. Architecture/planning subsystem
- src/architect is a distinct planning subsystem, separate from the agent loop and the orchestration layer.
- It likely produces high-level designs and decomposes tasks before implementation, which is why it has its own engine and types.
6. Perception and project understanding
- src/perception is the codebase analysis layer. It extracts repository structure and likely stores a graph/index of observed project facts.
- graph-store, queries, and extractor indicate a read/derive/store pattern: inspect files, normalize the result, then query it for planning and prompting.
- This subsystem feeds context into the agent/orchestrator so decisions are based on repository structure rather than only the raw prompt.
7. Tooling boundary: how the agent acts
- src/tools is the action surface exposed to the model. It includes filesystem operations, shell execution, tests, browser/web access, search, image/audio/transcript helpers, memory, notifications, and messaging integrations.
- This is the main side-effect boundary of the system: model decisions become tool calls, and tool results flow back into the agent loop.
- The tool set is broad enough to support local code changes and external research/integration workflows.
8. Provider abstraction
- src/providers isolates LLM backend differences behind a common interface.
- There are adapters for Anthropic, Google, OpenAI-compatible providers, plus fallback and resilient wrappers.
- This keeps the rest of the system provider-agnostic and lets the runtime survive transient provider failures.
9. Safety and execution constraints
- src/safety/permissions.ts and utility layers like retry, circuit breaker, and rate limiter define operational guardrails.
- These boundaries control what the agent can do, how failures are retried, and how external calls are stabilized.
- The design is clearly meant to keep autonomous execution bounded and observable.
10. Verification and quality gates
- src/verify performs post-action checks and has its own checks/types entrypoints.
- The README’s “I don’t try. I verify.” is reflected in this subsystem: run changes, inspect outcomes, and confirm correctness before reporting success.
- This is also where automated retry-on-failure behavior likely plugs in.
11. Learning, episode capture, and “Ruby”
- src/ruby is a self-improvement / meta-learning subsystem, with competence modeling, episode capture, training data, alternation, and fine-tuning support.
- It appears to analyze prior agent episodes and derive training or routing signals for future runs.
- This is separate from normal task execution: it turns accumulated experience into improved behavior.
12. Harnesses and weakness mining
- src/harness and src/integrations/harnesses.ts suggest a testing/benchmarking layer for generating or mining weaknesses from code/task examples.
- This likely supports regression discovery and evaluation, complementing verification by exploring where the agent fails.
13. Configuration, setup, and persistence
- src/config, src/setup, src/util, src/versioncheck.ts, and src/agent/session-store.ts handle defaults, project configuration, first-run behavior, environment parsing, and durable state.
- These modules are the glue between runtime behavior and local installation state.
- They define the boundary between “stateless prompt execution” and “persistent agent workspace/session behavior.”
14. Observability and UX surfaces
- src/viz likely powers dashboards/visual reporting, while graphify-out contains generated artifacts for graph visualization.
- The repo also includes packaged outputs and sample project assets under my-project, plus docs and generated media files.
- For an architecture diagram, these are downstream outputs and supporting artifacts rather than core runtime components.
15. Repo-level support material
- The .agents, .qwen, and related skill directories are a large knowledge/reference corpus for agent behavior and prompt/tooling patterns.
- They are not the primary runtime, but they materially support how the system is used and extended.
- In a diagram, treat them as documentation/skill assets feeding development and prompt design, not as live execution services.
16. End-to-end flow to show in a diagram
- User command enters via CLI or server.
- Configuration and permissions are loaded.
- Perception builds repository context.
- Orchestration/architect selects a plan and possibly specialist roles.
- The agent loop invokes providers and tools to edit/run/inspect.
- Verification checks the outcome.
- Session/state stores the result, and reporting/viz surfaces summarize what happened.
Main entry points: loop.ts Agent loop · orchestration/index.ts Orchestration · server/index.ts Server · perception/index.ts Perception
Components 20
Interfaces
User-facing entrypoints and long-lived runtime surfaces
Core runtime
Agent loop and workflow coordination
- Workflow engine · Coordinates task execution flows
src/workflows/engine.ts - Agent loop · Single-agent plan-act-verify cycle
src/agent/loop.ts - Session store · Persists agent/session state
src/agent/session-store.ts
Understanding
Repository analysis and planning subsystems
- Perception · Extracts and queries repository structure
src/perception/index.ts - Graph store · Stores observed repository facts and structure
src/perception/graph-store.ts - Orchestration · Routes work across specialist roles
src/orchestration/index.ts - Architect · High-level design and task decomposition
src/architect/engine.ts - Router · Chooses the next specialist or path
src/orchestration/router.ts - Executor · Runs orchestrated plans and specialist actions
src/orchestration/executor.ts
Actuation
Tools, providers, and execution guardrails
- Provider layer · Abstracts model backends and resilience wrappers
src/providers/factory.ts - Tool surface · Filesystem, shell, web, and integration tools
src/tools/index.ts - Permissions · Operational safety and execution constraints
src/safety/permissions.ts
Adaptation
Learning, verification, and failure feedback
- Verification · Checks results after actions complete
src/verify/index.ts - Ruby learning · Episode capture, competence, and fine-tuning signals
src/ruby/index.ts - Harnesses · Weakness mining and benchmark-style evaluation
src/harness/proposer.ts
Support
Configuration, setup, persistence, and observability
- Config · Defaults, project config, setup, and environment glue
src/config/defaults.ts - Viz · Dashboard and visual output surfaces
src/viz/index.ts - Global state · First-run and global installation state
src/setup/global-config.ts
Connections 22
- CLI → Config: loads config · CLI bootstraps runtime configuration
- Server → Config: loads config · Server startup uses project and global config
- CLI → Agent loop: starts · CLI enters the agent loop for a task
- Server → Workflow engine: serves · Server delegates long-lived work to workflows
- Workflow engine → Orchestration: orchestrates · Workflow engine hands execution to orchestration
- Agent loop → Perception: reads context · Agent loop gathers repository understanding
- Perception → Graph store: stores facts · Perception persists normalized repository graph data
- Agent loop → Provider layer: calls model · Agent loop invokes provider adapters for reasoning
- Agent loop → Tool surface: uses tools · Agent loop performs edits, searches, and checks through tools
- Tool surface → Permissions: constrained by · Tool execution is bounded by permissions and safety rules
- Orchestration → Router: routes · Orchestration selects specialists and next steps
- Orchestration → Executor: executes · Orchestration runs the chosen plan
- Orchestration → Architect: plans · Architect subsystem contributes higher-level decomposition
- Orchestration → Perception: contextualizes · Orchestration consults repository perception for decisions
- Verification → Agent loop: verifies · Verification validates outcomes produced by the loop
- Ruby learning → Orchestration: improves routing · Learning signals inform future orchestration behavior
- Ruby learning → Agent loop: improves loop · Captured episodes feed back into agent behavior
- Harnesses → Verification: complements · Harness evaluation supports verification and regression discovery
- Agent loop → Session store: persists · Loop stores session state and progress
- Server → Session store: resumes · Server session layer restores interaction state
- Viz → Session store: summarizes · Visualization surfaces session and run outcomes
- Global state → Config: feeds · Global setup informs configuration defaults and startup state