You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Codexia agent design draft for feedback (AI Coding Agent for GitHub Repositories)
So, ever since seeing "Roomote" on roocode's github i wanted to make an Agent that can effectively work as a human on github, answering to every issue, PR, and respond to mentions(and do what is asked). Look it up if you want a good example.
First, i looked for existing solutions, self-hosted, preferably.
SWE-agent: Has weird bugs. Heavy, because it requires docker and surprisingly heavy containers.
Opencode: Promising, and i successfully deployed it. Problems: It is very much not finished yet(still a new project). It runs strictly inside a github action, which, while pretty robust for simple-shot tasks, also limits how fast and how much it can do what it needs.
Also, it has only basic ability to make PR's and making one comment with whatever it finished with.
Now, i myself don't even have a good use case for a system like this, but, well, time was spent anyway. Idea is to have a self-hostable watcher that can spawn "orchestrator" run for every "trigger" it receives, which will handle everything needed, while also spawning sub-agents for tasks, so it can focus on providing feedback, commenting and deciding what to do next. Also, to yoink opencode's good use of github actions - it should also be able to run single instance of a agent inside action runner, for simple tasks like checking the submitted issue/PR for duplicates.
Currently, it is in the exploration/drafting stage, as i still need to get a clear vision of how this could be made. Agentic frameworks included to not reinvent the wheel. Language is python(as it is what i use most), though it is not set in stone. Though i rather stick to stuff i know for big projects like this.
The "CLI Pyramid" structure:
Tier 1 (The Daemon): A simple, native (and separate from tiers below) service that manages the job queue, SQLite audit logs, and Git worktree pool on the host. It's the resilient anchor.
Tier 2 (The Orchestrator): A temporary, containerized process spawned by the Daemon to handle one entire task (e.g., "Fix Bug #42").
Tier 3 (The Sub-Agent): Spawned by the Orchestrator, this is the specialized worker (Coder, Reviewer, Analyst). Uses a flexible model where Sub-Agents run as lightweight subprocesses inside the Orchestrator's container for speed, but can be configured per-persona to require a separate Docker sandbox for high-risk operations (like running user-contributed code).
The TL;DR of the Architecture:
The CLI Pyramid: Everything is based on one executable, codexia-cli. When the high-level manager (Tier 2) needs a task done, it literally executes the CLI again as a subprocess (Tier 3), giving it a specific prompt and toolset. This ensures perfect consistency.
Meta-Agent Management: The main orchestrator (Tier 2) is a "Meta-Agent." It doesn't use hardcoded graphs; it uses its LLM to reason, "Okay, first I need to spawn an Analyst agent, then I'll use the output to brief a Coder agent." The workflow is emergent.
Checkpointing: If the service crashes, the Daemon can restart the run from the last known good step using the --resume flag.
So, feedback welcome. I doubt i will finish this project. But it was an idea that kept reminding me of itself. Now i can finally put it in a #todo and forget about it lmao. Or hopefully maybe finish it at some point.
Date: October 2, 2025 Project: Open-Source AI Coding Agent for GitHub Repository Management
1. Introduction
1.1. Purpose
This document provides the authoritative technical specification for Codexia, a universal, goal-driven AI agent designed to autonomously manage GitHub repository tasks. It is architected for dual-mode operation: as a continuous, persistent Daemon for comprehensive repository management, and as an on-demand, ephemeral CLI tool for targeted tasks within CI/CD pipelines.
1.2. Scope
This specification covers the design and functionality of Codexia's complete operational model:
Daemon Mode: A lightweight, native (non-containerized) persistent service for continuous monitoring, workload management, and audit logging.
Agent Runtimes (Tiers 2 & 3): All agentic logic is executed within secure, containerized environments in the final production system.
GitHub Action (Standalone) Mode: The direct use of the core containerized codexia-cli tool within a GitHub Actions workflow.
1.3. Core Architectural Principles
Agentic Universality: The system's logic resides in natural language prompts and agent reasoning, not in hardcoded workflows.
The CLI Pyramid: The system is built on a single, powerful CLI tool (codexia-cli). Higher-level processes (Orchestrators) are themselves CLI instances that spawn lower-level CLI instances (Sub-Agents).
Dual-Mode Parity: The core agentic logic, personas, and tool implementations are identical in both Daemon and Standalone modes, ensuring consistent and predictable behavior.
Pragmatic Persistence (Daemon Mode): The Daemon uses a file-based database (SQLite) for robust, transactional audit logging and crash recovery, with optional Redis integration for queuing in high-load scenarios.
Auditable and Ephemeral: Agent runs are temporary processes whose sole persistent artifact is a complete, unabridged transcript.
Security by Default: The system employs a "whitelist" permissions model as the default for all agentic runs.
Hierarchical Configuration: The agent's behavior is defined by a global base configuration which can be progressively overridden by repository-specific settings, empowering local team conventions.
1.4. Critical Note: Staged Adoption of Sandboxing
This document specifies the final, production-ready state of the system, in which Docker-based sandboxing for all agent execution is a mandatory security requirement.
However, to accelerate the development lifecycle and simplify debugging of core agentic logic, the implementation will proceed in stages. The enforcement of containerized execution for agent runs is deferred until the final production hardening phase.
Development & Staging Phases: The Daemon will spawn agent processes (codexia-cli run ...) directly on the host within a standard Python virtual environment. This allows for easier debugging, profiling, and direct interaction.
Production Phase (Final Release): The process spawning mechanism will be switched to docker run ... as specified in this document. All features related to container networking, resource management, and secret injection must be implemented and tested prior to this final stage.
2. System Architecture: The Hybrid Native/Containerized Model
Codexia's architecture leverages the strengths of both native and containerized execution to achieve a balance of simplicity, security, and performance. It is a hierarchical system that separates the persistent service from the ephemeral agent logic, ensuring reliability and security.
+-------------------------------------------------------------------+
| Tier 1: The Daemon (Native System Service) |
| - Runs as a `systemd` or similar native process. |
| - Listens for Webhooks & Schedules. |
| - Manages SQLite DB, Checkpoints, and Worktree Pool on host FS. |
+-------------------------------------------------------------------+
| (Spawns Process: `docker run ...` in Production)
v
+-------------------------------------------------------------------+
| Tier 2: The Orchestrator Run (Ephemeral, Containerized Meta-Agent)|
| - Runs `codexia-cli` inside a Docker container. |
| - Manages a high-level task (e.g., "Resolve #123"). |
| - Spawns & manages Tier 3 Sub-Agent containers. |
+-------------------------------------------------------------------+
| (Spawns Process: `docker run ...` in Production)
v
+-------------------------------------------------------------------+
| Tier 3: The Sub-Agent Run (Ephemeral, Containerized Worker Agent) |
| - Runs `codexia-cli` inside a Docker container. |
| - Executes a specific, short-term sub-task. |
+-------------------------------------------------------------------+
3. Tier 1: The Daemon (Native Service)
The Daemon is a continuously running service designed for reliability and robust workload management. It is installed and run directly on the host operating system.
3.1. Responsibilities and Execution
Execution: Runs as a native system service (e.g., via systemd).
Process Spawning: Spawns isolated Orchestrator Run processes. Note: In development, this will be a direct subprocess. In production, this will be a docker run command.
Configuration Loading: When spawning an Orchestrator, the Daemon MUST ensure the contents of the repository's .github/codexia.yaml are made available to the agent's runtime environment (e.g., via a mounted file or environment variable).
State & Audit: Manages the SQLite database and worktree pool directly on the host's filesystem.
Transcript Handling (Success & Failure): When an Orchestrator process finishes, regardless of its exit status (success or failure), the Daemon MUST collect the entire, unabridged transcript. This transcript is saved to the audit database to ensure that debugging information from failed runs is always preserved.
3.2. Persistence Layer (SQLite)
The Daemon uses a single-file SQLite database (codexia_daemon.db) for its persistence needs, with optional Redis integration for queuing in high-load scenarios. SQLite remains the primary store for audits, runs, transcripts, and checkpoints. For backups and analysis, export tools MUST be provided, such as CLI commands (codexia-cli export-db --format csv/json) to dump data for external processing or archiving.
3.3. Daemon Configuration
The Daemon's own configuration MUST be loaded from a YAML file, with overrides from environment variables.
# The path to the SQLite database file.database_path: "/etc/codexia/daemon.db"# Optional Redis configuration for queuing in high-load scenarios.redis:
enabled: falseurl: "redis://localhost:6379/0"# The root directory for storing Git worktrees and run-specific artifacts.workspace_root: "/var/lib/codexia/workspaces"# The maximum number of Orchestrator runs that can execute concurrently.max_concurrent_runs: 10# The default timeout in seconds for a single Orchestrator run.task_timeout_seconds: 3600# 1 hour# Logging configuration.logging:
level: "INFO"# DEBUG, INFO, WARNING, ERRORfile_path: "/var/log/codexia/daemon.log"# Webhook server configuration.server:
host: "0.0.0.0"port: 8080
3.4. Daemon CLI (codexia-daemon-cli)
The codexia-daemon-cli is a separate, complementary tool to the Daemon service, providing an administrative interface for management, introspection, and maintenance. It separates the operational plane (Daemon service) from the control plane (administrative tasks), ensuring the Daemon remains lean, reliable, and secure.
Purpose: Acts as a "mechanic's toolkit" for human administrators or scripts to interact with the Daemon's resources without bloating the service.
Execution: Runs ephemerally with the invoking user's privileges (e.g., root for backups).
Key Commands: Includes groups like db for database operations (e.g., export-runs, backup).
Rationale: Enhances security (least privilege), usability (simple introspection), and automation (scriptable), preventing direct database tampering.
4. Tier 2: The Orchestrator Run (Ephemeral Meta-Agent)
The Orchestrator is an ephemeral, containerized meta-agent responsible for high-level task coordination.
4.1. Responsibilities and Execution
Execution: Runs as codexia-cli run --persona orchestrator ... inside a Docker container (in production), spawned by the Daemon.
Task Management: Breaks down complex goals into sub-tasks, using reasoning to delegate to Tier 3 Sub-Agents via the spawn_agent tool.
State Handling: Maintains transactional integrity by committing workspace changes to Git branches after each successful sub-task. Supports resilience features like circuit breakers for LLM calls (to prevent cascading failures during outages) and auto-retries with exponential backoff (e.g., 1s, 2s, 4s delays up to 5 attempts).
Sub-Agent Spawning: By default, spawns Sub-Agents as subprocesses within the same container for efficiency in a "lightweight" mode (configurable via daemon.yaml or env). This leverages the container's existing security boundary. For stricter isolation, a "sandbox" mode can be enabled to spawn Sub-Agents in child containers, or per-persona via requires_sandbox: true.
Resumption: Includes a "resume" CLI flag (codexia-cli resume --run-id <id>) to restart from checkpoints, enabling manual or AI-driven intervention.
4.2. Configuration and Tools
Loads hierarchical personas, with access to orchestration-specific tools like spawn_agent.
Manages context condensation and full transcripts for auditing.
4.3. Resilience Features
Circuit Breaker: All external API calls (especially to the LLM provider) MUST be wrapped in a circuit breaker pattern. After a configured number of consecutive failures, the breaker will "trip" and fail fast for a cooldown period, preventing system overload.
Automatic Retries: Transient network errors or API failures MUST trigger an automatic retry mechanism with exponential backoff.
5. Tier 3: The Sub-Agent Run (Ephemeral Worker Agent)
The Sub-Agent is a specialized, ephemeral worker for atomic tasks.
5.1. Responsibilities and Execution
Execution: Runs as codexia-cli run --persona <specialized> ..., spawned by the Orchestrator. In "lightweight" mode (default), runs as a subprocess inside the Orchestrator's container for efficiency and reduced overhead. In "sandbox" mode (configurable), runs in a dedicated child container for enhanced isolation.
Task Focus: Executes specific sub-tasks (e.g., code generation, review) using tools and ReAct loops, inheriting the shared workspace.
Resilience: Inherits circuit breakers and auto-retries from the Orchestrator for LLM interactions.
Output: Returns results and transcripts to the Orchestrator, ensuring no persistent state beyond the shared workspace.
6. Agent Execution Environment (Production)
All agentic logic (Tiers 2 & 3) MUST be executed within a secure, containerized environment using Docker in the final production system.
6.1. The Agent Container Image
A single, minimal Docker image (codexia-agent:latest) will be built containing the codexia-cli executable and all its Python dependencies.
6.2. Dockerfile Specification
The Dockerfile for the codexia-agent image MUST perform the following:
Use a minimal, security-hardened base image (e.g., python:3.11-slim-bookworm).
Install all necessary Python dependencies via the project's dependency manager.
Install required external binaries. This includes tools that agent personas might need to execute via the shell tool, such as:
The official GitHub CLI (gh).
git.
Other common command-line utilities (e.g., curl, jq).
Set up a non-root user and switch to it for running the agent process (USER codexia).
6.3. Secure Networking Model: Whitelisted Access
A whitelisted networking model MUST be implemented for production containers, restricting outbound access to essential API endpoints (GitHub, LLM Provider).
6.4. Resource Management for Efficiency
The Daemon MUST apply strict, configurable resource limits (CPU, memory) to every agent container it spawns.
7. Shared Workspace Mechanism
Communication and state handoff between the Tier 2 Orchestrator and its Tier 3 Sub-Agents are achieved via a shared filesystem, managed by the Daemon and facilitated by Docker volume mounts.
8. GitHub Action (Standalone) Mode
The operation of codexia-cli within GitHub Actions is a special case that combines the roles of Tiers 2 and 3 into a single, self-contained container run. When running in a local Git repository context, the CLI MUST automatically detect and load the .github/codexia.yaml file to apply any persona overrides for the run, ensuring behavioral parity with Daemon mode.
9. Core Agent Capabilities
9.1. Context Window Management
Agents MUST implement context condensation to manage long-running tasks. This condensation affects the agent's running context only. A separate, unabridged transcript of all original messages MUST be maintained and saved.
9.2. The Hierarchical Persona System
Agent behavior is defined by a hierarchical configuration system that empowers repository-specific customization.
Loading Mechanism:
When an agent run is initialized with a specific persona (e.g., "coder"), the final persona configuration is constructed using the following three-step process:
Load Base Persona: The system first loads the base definition from the global configuration directory (e.g., /etc/codexia/personas/coder.yaml). This file defines the default name, system_prompt, and permissions for that role.
Check for Overrides: The system then checks the repository's .github/codexia.yaml file for a persona_overrides section.
Deep Merge: If an override for the requested persona exists, its contents are deeply merged into the base persona configuration. This means nested values (like rules within permissions) are merged, and top-level values (like system_prompt) are replaced.
This hierarchical approach allows system administrators to define sane, secure defaults globally, while permitting individual teams to fine-tune agent behavior to match their local conventions.
Example Base Persona (/etc/codexia/personas/coder.yaml):
name: CoderAgentsystem_prompt: "You are a software engineer. Your task is to write correct and efficient code."permissions:
mode: "whitelist"rules:
git: ["get_diff", "apply_patch"]code: ["*"]sandbox: ["*"]requires_sandbox: false
Example Repository Override (.github/codexia.yaml):
# ... other repo settings ...persona_overrides:
coder:
system_prompt: "You are a Senior Staff Engineer at Acme Corp. You MUST write Python code that adheres to the PEP-8 style guide and includes comprehensive docstrings. Your tone is formal and professional."permissions:
rules:
# Add the 'shell' tool for running 'make format'shell: ["make format"]requires_sandbox: true
In this example, the Coder agent for this specific repository would use the custom prompt, have access to git, code, sandbox, and the newly allowed shell command, and require sandboxing.
9.3. The Transactional Workspace Model
The Orchestrator MUST commit the state of the shared workspace to its local Git branch after each successful Sub-Agent run.
9.4. Testing and Validation
Webhook Simulation: Phase 1 testing MUST include a suite of tests that simulate various GitHub webhook payloads to validate the Daemon's parsing and queuing logic.
Chaos Testing: Phase 4 testing MUST include a chaos engineering suite. This includes randomly terminating Orchestrator containers mid-run to verify that the Daemon's checkpoint/resume mechanism correctly recovers the task.
10. Security
10.1. Authentication
Use short-lived, repository-scoped installation access tokens (Daemon) or the GITHUB_TOKEN (Action).
10.2. Secret Injection Mechanism (Daemon to Container)
The native Daemon is responsible for securely passing secrets into the ephemeral agent containers. This MUST be done using Docker's environment variable injection mechanism.
The Daemon will generate or retrieve the necessary run-specific tokens (e.g., a GitHub installation access token).
It will construct the docker run command with an -e flag for each secret.
The agent's behavior for a specific repository is controlled by a configuration file located at .github/codexia.yaml.
11.1. Configuration Schema
# Schema Version: 1.1# Defines the primary operational strategy for the agent in this repository.mode: "conservative"# ENUM: "conservative", "balanced", "aggressive"# conservative: Will not open PRs without a specific request. Focuses on analysis and review.# balanced: Can open PRs for bugs, but not for proactive feature work or refactoring.# aggressive: Proactively opens PRs for fixes, features, and refactoring.# Context window management settings for all agents running in this repository.context_management:
model: "anthropic/claude-3-5-sonnet-20240620"limit: 180000# The token limit for the primary model.condensation_trigger_ratio: 0.8# Condense when context exceeds 80% of the limit.condensation_model: "anthropic/claude-3-haiku-20240307"# A cheaper model for summarizing.# Per-repository overrides for global agent personas. Allows fine-tuning of agent# behavior, such as prompts and permissions, for local conventions.persona_overrides:
# Key is the name of the persona file (e.g., 'coder.yaml' -> 'coder').coder:
system_prompt: "You are a Senior Staff Engineer at Acme Corp. You MUST write Python code that adheres to the PEP-8 style guide and includes comprehensive docstrings."permissions:
# This will be deep-merged with the base persona's permissions.# It adds a new rule without removing existing ones.rules:
shell: ["make format", "make lint"]reviewer:
system_prompt: "You are a code reviewer focused on security and performance. All other concerns are secondary."requires_sandbox: true
This document outlines the phased implementation of the Codexia system. All development tasks MUST directly map to a requirement in Design Document: Codexia. The primary objective is to construct the dual-mode system, starting with the core agent runtime and progressively building the persistent Daemon and production-ready features.
2. Methodology
Sequential Phasing: Development is divided into four distinct phases. Each phase must be completed and all acceptance criteria met before the next phase begins.
Specification-Driven: Every implemented feature must have a corresponding entry in the design document.
Test-Driven Development (TDD): For each new component, a suite of pytest unit and integration tests must be written and pass before the component is considered complete.
Continuous Integration (CI): All code submissions must pass an automated pipeline of linting, testing, and security scanning before being merged.
Staged Prototyping: Core user-facing interfaces, such as the GitHub Action, will be prototyped early in the development cycle using simpler technology (e.g., local script execution) to enable rapid testing, with production hardening (e.g., containerization) deferred to the final phase.
Phase 1: The Universal Agent Runtime (codexia-cli)
Goal: To build the core, reusable, and stateless agent execution engine. This phase will deliver a functional CLI and a working prototype of the GitHub Action.
Milestone 1.1: Project Initialization & CI
Objective: Establish a robust, automated development environment.
Tasks:
Initialize the Git repository with a standard Python project structure.
Configure poetry for dependency management.
Implement pre-commit hooks for linting (ruff) and formatting (black).
Create the initial GitHub Actions workflow for CI (.github/workflows/ci.yml) that runs pytest on every push.
Acceptance Criteria:
✅ A pull request with a simple "hello world" function and a passing pytest test successfully triggers and passes the CI pipeline.
Milestone 1.2: CLI Framework & Configuration
Objective: Implement the command-line interface and the hierarchical persona loading system.
Tasks:
Implement the codexia-cli run command structure using click.
Implement argument parsing for [PROMPT], --prompt-file, --model, and --permissions.
Create the hierarchical configuration loading logic as specified in Design Doc 9.2. It must load a base persona and deep-merge a repository-specific override.
Define the initial persona files (e.g., /etc/codexia/personas/analyst.yaml) in the project structure.
Acceptance Criteria:
✅ Running codexia-cli run --help displays all specified arguments and options.
✅ A unit test successfully demonstrates that a persona_override from a mock .github/codexia.yaml correctly merges with a base persona file.
Objective: Implement the fundamental agent reasoning loop and context handling.
Tasks:
Create the BaseAgent class that encapsulates the ReAct (Reason, Act, Observe) loop.
Implement the context condensation logic as specified in Design Doc 9.1.
Create a mock tool registry for initial testing.
Acceptance Criteria:
✅ A unit test with a long conversation history successfully triggers the context condensation mechanism, replacing the history with a summary.
✅ A simple agent run can complete a multi-step task using mock tools.
Milestone 1.4: Tool & Permission System
Objective: Implement the agent's capabilities and the security model that governs them.
Tasks:
Implement the ToolRegistry and the permission filtering logic (whitelist/blacklist modes).
Implement at least one tool from each namespace (github, git, shell) as a proof of concept.
Integrate the permission filter into the codexia-cli run command, ensuring the agent only receives the allowed tools.
Acceptance Criteria:
✅ A test run with a "whitelist" permission set successfully allows an agent to use a specified tool.
✅ A second test run with the same "whitelist" fails with a clear error when the agent attempts to use a tool not on the list.
Milestone 1.5: Initial GitHub Action Prototype
Objective: Create a working, non-containerized prototype of the GitHub Action to enable early testing and integration.
Tasks:
Create an action.yml file that defines a composite action.
The action's implementation will use runs: steps to:
a. Check out the repository.
b. Set up a Python environment using actions/setup-python.
c. Install project dependencies using poetry.
d. Execute the codexia-cli run command, passing through the action's inputs.
Document how to use this local action (uses: ./) within the project's own workflows for testing.
Acceptance Criteria:
✅ A sample workflow within the project repository successfully calls the local composite action (uses: ./) and completes a simple prompt-driven task.
Milestone 1.6: Webhook Simulation Tests
Objective: Expand testing to include webhook simulations for early validation of event handling.
Tasks:
Implement mock webhook payloads for common GitHub events (e.g., issue opened, PR created).
Add integration tests that simulate sending these payloads to a mock Daemon endpoint and verify queuing behavior.
Acceptance Criteria:
✅ Tests successfully simulate webhook events and confirm tasks are queued without errors.
Phase 2: The Daemon & Orchestration Layer
Goal: To build the persistent, native service that manages and orchestrates agent runs.
Milestone 2.1: Daemon Service & Persistence
Objective: Establish the continuously running service and its database.
Tasks:
Create the Daemon application skeleton with systemd service files.
Implement configuration loading logic for daemon.yaml as specified in Design Doc 3.3.
Set up SQLite database with SQLAlchemy and Alembic for migrations.
Add optional Redis integration for queuing, enabled via config; fallback to in-memory for low-load.
Implement export tools (codexia-cli export-db --format csv/json) for SQLite backups and analysis.
Implement Daemon CLI commands for database management (e.g., codexia-daemon-cli db export-runs, backup).
Acceptance Criteria:
✅ The Daemon service can be started, stopped, and restarted via systemctl.
✅ On first run, the Daemon creates the codexia_daemon.db file and applies all Alembic migrations.
✅ Redis queuing toggles correctly via config; export tools produce valid dumps.
✅ Daemon CLI successfully exports and backs up data.
Milestone 2.2: Webhook Ingress & Task Queuing
Objective: Enable the Daemon to receive and queue tasks from GitHub.
Tasks:
Implement FastAPI application with GitHub webhook signature verification.
Design and implement database schema for repositories, runs, and events.
Set up Redis connection and basic task queue structure if enabled.
Create configuration management with environment variables and YAML files.
Implement structured logging with correlation IDs.
Acceptance Criteria:
✅ Webhook gateway successfully receives and validates GitHub webhooks.
✅ Database operations work correctly with proper migrations.
✅ Configuration can be loaded from multiple sources (env, YAML, database).
Milestone 2.3: Git Repository Management
Objective: Manage local Git repository clones and worktrees.
Tasks:
Implement RepositoryManager class with GitPython integration.
Create worktree allocation and cleanup mechanisms.
Implement repository-level and worktree-level locking.
Add error handling and recovery for Git operations.
Create unit tests for Git operations with test repositories.
Acceptance Criteria:
✅ Multiple concurrent jobs can operate on the same repository safely.
✅ Worktrees are properly created, used, and cleaned up.
✅ Git operations handle network failures and lock conflicts gracefully.
Milestone 2.4: Agent Framework Integration
Objective: Integrate agent framework with basic definitions.
Tasks:
Set up agent framework with basic conversable agents.
Implement tool registration and execution framework.
✅ Automatic labeling matches human expectations on test issues.
Milestone 2.6: Root Cause Analysis
Objective: Implement code exploration for analysis.
Tasks:
Implement CodeExplorerAgent with file system analysis tools.
Create tools for parsing stack traces and error messages.
Build code location identification using AST analysis.
Implement hypothesis generation with LLM reasoning.
Add investigation plan creation and documentation.
Acceptance Criteria:
✅ Agent identifies code locations from stack traces.
✅ Hypothesis generation provides logical root cause suggestions.
Phase 3: Production Hardening
Goal: To implement the mandatory security, reliability, and observability features required for production deployment.
Milestone 3.1: Containerization & Sandboxing
Objective: Transition from direct process execution to secure, containerized agent runs.
Tasks:
Create the Dockerfile for the codexia-agent image as specified in Design Doc 6.2. It MUST install gh and other required binaries.
Modify the Daemon's process spawner to use docker run instead of subprocess.Popen.
Implement the logic for Docker volume mounts to facilitate the shared workspace.
Implement the secret injection mechanism using -e flags as specified in Design Doc 10.2.
Add "lightweight" mode: Sub-Agents spawn as subprocesses in the Orchestrator's container by default; configurable "sandbox" mode spawns them in child containers, or per-persona via requires_sandbox.
Acceptance Criteria:
✅ The Daemon now successfully executes Orchestrator and Sub-Agent runs inside Docker containers.
✅ A test run confirms that secrets (e.g., GITHUB_TOKEN) are available inside the container but are not logged.
✅ Lightweight mode reduces overhead for short tasks; sandbox mode enforces isolation.
Milestone 3.2: Security Hardening
Objective: Finalize all security controls.
Tasks:
Implement secure networking policies for the production Docker environment.
Implement resource limit enforcement (CPU, memory) in the docker run commands issued by the Daemon.
Perform a full dependency scan and security audit of the final container image.
Acceptance Criteria:
✅ An agent container attempting to access a non-whitelisted network address fails.
✅ A run that exceeds its memory limit is automatically killed by Docker.
✅ Security scans (e.g., trivy) report zero critical or high vulnerabilities.
Milestone 3.3: Observability
Objective: Provide comprehensive monitoring and logging for the production system.
Tasks:
Integrate a Prometheus client into the Daemon to expose key metrics (runs_active, runs_completed_total, run_duration_seconds).
Implement structured JSON logging for all Daemon and agent processes.
Create a sample Grafana dashboard configuration for visualizing the key metrics.
Acceptance Criteria:
✅ A running Daemon exposes a /metrics endpoint that can be scraped by Prometheus.
✅ All logs are produced in a machine-parsable JSON format.
Milestone 3.4: Resilience Features
Objective: Add fault-tolerant mechanisms for production reliability.
Tasks:
Implement circuit breakers for LLM API calls to halt retries during detected outages.
Add auto-retries with exponential backoff for transient failures (e.g., network errors).
Implement the "resume" CLI flag for restarting runs from checkpoints.
Date: October 2, 2025 Purpose: This document provides a comprehensive, code-centric reference for the implementation of the Codexia AI Coding Agent. It details the core architectural patterns, critical subsystem implementations, and provides authoritative code examples. It is the primary engineering guide for AI-driven development.
1. Core Architectural Patterns
1.1. The Three-Tier Execution Model
Codexia's architecture separates the persistent service from the ephemeral agent logic, ensuring reliability and security.
Tier 1: The Native Daemon: A lightweight, persistent system service responsible for listening, spawning, and auditing. It is the only non-containerized component.
Tier 2: The Orchestrator Run: An ephemeral, containerized meta-agent that manages a high-level task from start to finish.
Tier 3: The Sub-Agent Run: An ephemeral, containerized worker agent that executes a specific sub-task delegated by the Orchestrator.
1.2. The CLI Pyramid
The entire system is built upon a single, universal executable: codexia-cli. Higher-level tiers orchestrate lower-level tiers by spawning them as new CLI processes within containers. This ensures perfect behavioral parity between the Daemon's orchestrated runs and standalone GitHub Action runs.
+-------------------------------------------------------------+
| Tier 1: Daemon (Native Process) |
| - Listens for events. |
| - Spawns a new Docker container: |
| `docker run codexia-agent:latest run --persona orchestrator ...` |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Tier 2: Orchestrator (Containerized CLI Process) |
| - Manages a high-level goal. |
| - Needs to delegate a sub-task. |
| - Spawns a new Docker container from within its container: |
| `docker run codexia-agent:latest run --persona coder ...` |
+-------------------------------------------------------------+
|
v
+-------------------------------------------------------------+
| Tier 3: Sub-Agent (Containerized CLI Process) |
| - Executes a specific task. |
| - Terminates and returns result to Orchestrator. |
+-------------------------------------------------------------+
1.3. Pragmatic Persistence & Resilience
The system is designed for robust, start-to-finish autonomous operation.
Persistence: A primary SQLite database serves as the unchangeable audit log. An optional Redis layer can be enabled for high-throughput task queuing.
Resilience: All external API calls are protected by circuit breakers and automatic retries with exponential backoff.
Recovery: All Orchestrator runs are checkpointed, allowing the Daemon to resume interrupted tasks seamlessly.
2. Tier 1: The Native Daemon Implementation
The Daemon is the persistent anchor of the system.
2.1. Persistence Layer (SQLAlchemy Models)
These models directly implement the schema defined in Design Document for the SQLite database.
importhmacimporthashlibfromfastapiimportFastAPI, Request, BackgroundTasks, HTTPException# Assume `queue_task` is a function that adds a validated event to the Daemon's run queue.# from .queue import queue_taskdaemon_app=FastAPI()
WEBHOOK_SECRET=os.getenv("GITHUB_WEBHOOK_SECRET", "").encode('utf-8')
@daemon_app.post("/api/v1/webhook/github")asyncdefgithub_webhook_endpoint(request: Request, background_tasks: BackgroundTasks):
"""Receives, validates, and queues GitHub webhook events."""payload_body=awaitrequest.body()
signature_header=request.headers.get("X-Hub-Signature-256")
ifnotsignature_header:
raiseHTTPException(status_code=401, detail="Missing signature header")
expected_signature="sha256="+hmac.new(WEBHOOK_SECRET, payload_body, hashlib.sha256).hexdigest()
ifnothmac.compare_digest(expected_signature, signature_header):
raiseHTTPException(status_code=401, detail="Invalid signature")
event_payload=awaitrequest.json()
delivery_id=request.headers.get("X-GitHub-Delivery")
# Add the validated task to the background queue for processing.background_tasks.add_task(queue_task, delivery_id, event_payload)
return {"status": "queued"}
2.3. Agent Process Spawner
This component is responsible for launching containerized agent runs.
importdockerimportuuidclassAgentSpawner:
def__init__(self):
self.docker_client=docker.from_env()
defrun_orchestrator(self, run_id: uuid.UUID, context: dict, secrets: dict, workspace_path: str):
""" Spawns a Tier 2 Orchestrator agent in a secure Docker container. This is the production implementation. """# Construct environment variables for secretsenv_vars= {key: valueforkey, valueinsecrets.items()}
# Construct the CLI commandcommand= [
"run",
"--persona", "orchestrator",
"--context-json", json.dumps(context),
# Add other necessary CLI flags
]
container=self.docker_client.containers.run(
image="codexia-agent:latest",
command=command,
environment=env_vars,
volumes={
workspace_path: {'bind': '/workspace', 'mode': 'rw'}
},
network_mode="default", # Or a restricted networkmem_limit="2g",
cpu_quota=100000, # 1 CPU coredetach=True, # Run in the backgroundremove=True, # Auto-remove container on exit
)
returncontainer.iddefrun_orchestrator_dev(self, run_id: uuid.UUID, context: dict, secrets: dict, workspace_path: str):
""" Spawns a Tier 2 Orchestrator agent as a direct subprocess for development. """importsubprocessenv=os.environ.copy()
env.update(secrets)
command= [
"codexia-cli",
"run",
"--persona", "orchestrator",
"--context-json", json.dumps(context),
]
process=subprocess.Popen(command, env=env, cwd=workspace_path)
returnprocess.pid
2.4. Persistence Layer & Tooling
SQLAlchemy Models: The database schema is managed via SQLAlchemy, as defined in Design Document 3.2.
Database Management CLI: A dedicated CLI is provided for database maintenance.
# codexia_daemon_cli/db.pyimportclickfromcodexia_daemon.databaseimportSession, Run@click.group()defdb():
"""Commands for managing the Daemon's database."""pass@db.command()@click.option('--format', type=click.Choice(['json', 'csv']), default='json')defexport_runs(format):
"""Export completed run data for analysis."""session=Session()
runs=session.query(Run).all()
# ... logic to serialize runs to JSON or CSV and print to stdout ...click.echo("Export complete.")
@db.command()defbackup():
"""Create a backup of the SQLite database file."""# ... logic to safely copy the database file to a timestamped backup ...click.echo("Backup created.")
2.5. Webhook Ingress (FastAPI with Optional Redis)
The entrypoint now supports a high-throughput Redis queue.
# codexia_daemon/server.pyfromfastapiimportFastAPIfrom .configimportsettingsfrom .queueimportget_queue# This function returns a RedisQueue or InMemoryQueue instancedaemon_app=FastAPI()
task_queue=get_queue(settings)
@daemon_app.post("/api/v1/webhook/github")asyncdefgithub_webhook_endpoint(request: Request):
# ... HMAC signature validation logic ...event_payload=awaitrequest.json()
delivery_id=request.headers.get("X-GitHub-Delivery")
# The queue object abstracts away whether it's Redis or in-memory.awaittask_queue.enqueue({"delivery_id": delivery_id, "payload": event_payload})
return {"status": "queued"}
2.6. Orchestrator Spawner (Production)
This component launches Tier 2 Orchestrator containers.
importclickimportjsonfromcodexia_core.agentsimportBaseAgentfromcodexia_core.configimportload_final_persona_configfromcodexia_core.toolsimportget_filtered_tool_registry@click.command()@click.argument('prompt', required=False)@click.option('--prompt-file', '-f', type=click.Path(exists=True))@click.option('--model', '-m', envvar='CODEXIA_MODEL')@click.option('--persona', required=True, help="The agent persona to use.")@click.option('--permissions', '-p', type=str, envvar='CODEXIA_PERMISSIONS')@click.option('--context-json', type=str, default='{}')@click.option('--resume', is_flag=True, help="Resume from a checkpoint for the given run ID.")@click.option('--run-id', type=str, help="Run ID for resumption.")defrun(prompt, prompt_file, model, persona, permissions, context_json, resume, run_id):
""" Runs a universal, goal-driven AI agent for a single task. """ifnotpromptandnotprompt_file:
raiseclick.UsageError("Either PROMPT argument or --prompt-file option is required.")
ifpromptandprompt_file:
raiseclick.UsageError("Cannot use both PROMPT argument and --prompt-file option.")
ifprompt_file:
withopen(prompt_file, 'r') asf:
final_prompt=f.read()
else:
final_prompt=prompt# 1. Load context and persona configurationcontext=json.loads(context_json)
final_prompt=final_prompt.format(**context)
persona_config=load_final_persona_config(persona_name=persona) # Implements hierarchical loading# 2. Apply permissionspermissions_json=json.loads(permissions) ifpermissionselsepersona_config.get("permissions")
allowed_tools=get_filtered_tool_registry(permissions_json)
# 3. Instantiate and run the agentagent=BaseAgent(
config=persona_config,
tools=allowed_tools,
llm_model=model
)
ifresumeandrun_id:
# Load checkpoint from persistence and resume executionagent.load_checkpoint(run_id)
# This is a blocking call that runs the agent's full ReAct loop.final_transcript=agent.execute_task(final_prompt)
# The final, unabridged transcript is printed to stdout for the calling process (Daemon) to collect.print(json.dumps(final_transcript))
if__name__=='__main__':
run()
4. Core Agent & Persona Implementation (codexia_core)
4.1. Base Agent with Context Condensation
classBaseAgent:
def__init__(self, config: dict, tools: list, llm_model: str):
self.config=configself.tools=toolsself.llm_model=llm_modelself.history= [{"role": "system", "content": config.get("system_prompt", "")}]
self.full_transcript=self.history[:]
def_should_condense(self) ->bool:
# Logic to check token count against context_management config# ... returns True if condensation is needed ...passdef_condense_context(self):
# Logic to call the condensation_model and replace history# ...# self.history = [system_prompt, condensed_summary, recent_messages]passdefexecute_task(self, initial_prompt: str) ->dict:
self.history.append({"role": "user", "content": initial_prompt})
self.full_transcript.append({"role": "user", "content": initial_prompt})
whileTrue: # The ReAct Loopifself._should_condense():
self._condense_context()
# 1. Reason: Call LLM with current history to get next action (tool call or final answer)# llm_response = call_llm(self.llm_model, self.history)# 2. Act: If it's a tool call, execute it and get the result.# tool_result = self.tools[tool_name](**tool_args)# 3. Observe: Append the tool result to history and the transcript.# self.history.append({"role": "tool", "content": tool_result})# self.full_transcript.append(...)# If the LLM provides a final answer, break the loop.# if is_final_answer(llm_response):# breakreturnself.full_transcript
4.2. Orchestrator's spawn_agent Tool
This tool is a key part of the Tier 2 Orchestrator's persona.
defspawn_agent(persona: str, prompt: str) ->dict:
""" Spawns a new, ephemeral Sub-Agent to perform a specific task. This tool is only available to Orchestrator personas. """# This function is essentially a wrapper around the `AgentSpawner` class.# It constructs the CLI command and context for the new Sub-Agent.# It blocks until the subprocess completes, then captures and returns# the stdout, which contains the Sub-Agent's final transcript.# ... logic to call `docker run codexia-cli run --persona ...` ...# return {"status": "success", "transcript": sub_agent_transcript}pass
5. Critical Subsystem: Asynchronous Repository Pool
This implementation provides safe, concurrent access to Git repositories. It is used by the Native Daemon to manage the host's worktree pool.
importasyncioimportgitfrompathlibimportPathclassRepositoryPool:
def__init__(self, base_path: Path):
self.base_path=base_pathself._locks: dict[str, asyncio.Lock] = {}
asyncdef_get_lock(self, repo_name: str) ->asyncio.Lock:
ifrepo_namenotinself._locks:
self._locks[repo_name] =asyncio.Lock()
returnself._locks[repo_name]
asyncdefcreate_worktree(self, repo_name: str, run_id: str) ->Path:
""" Creates an isolated Git worktree for a specific run. This is an I/O-bound operation and uses threads. """repo_path=self.base_path/f"{repo_name.replace('/', '_')}.git"work_path=self.base_path/"worktrees"/run_idasyncwithawaitself._get_lock(repo_name):
ifnotrepo_path.exists():
# Run blocking clone in a separate threadawaitasyncio.to_thread(
git.Repo.clone_from, f"https://github.com/{repo_name}.git", repo_path, bare=True
)
repo=git.Repo(repo_path)
# Run blocking fetch and worktree add in separate threadsawaitasyncio.to_thread(repo.remote('origin').fetch)
awaitasyncio.to_thread(repo.git.worktree, 'add', str(work_path))
returnwork_pathasyncdefcleanup_worktree(self, work_path: Path):
# ... logic to safely remove the worktree and prune the reference, using asyncio.to_thread ...pass
6. GitHub Action Implementation (action.yml)
This is the final, production-ready version of the Action, using the containerized agent.
# action.ymlname: 'Codexia Agent'description: 'Runs a universal, goal-driven AI agent for a single task.'author: 'Your Org'inputs:
prompt:
description: 'The natural language prompt for the agent. Required if prompt-file is not set.'required: falseprompt-file:
description: 'Path to a file containing the prompt. Required if prompt is not set.'required: falsemodel:
description: 'The LLM model to use.'required: falsepersona:
description: 'The agent persona to use.'required: truepermissions:
description: 'A JSON string defining tool permissions.'required: falsecontext-json:
description: 'A JSON string of context variables to inject into the prompt.'required: falsedefault: '{}'github-token:
description: 'The GitHub token for API access.'required: trueruns:
using: 'docker'image: 'docker://ghcr.io/your-org/codexia-agent:v1.0'env:
GITHUB_TOKEN: ${{ inputs.github-token }}CODEXIA_PERMISSIONS: ${{ inputs.permissions }}CODEXIA_MODEL: ${{ inputs.model }}args:
- 'run'
- '--persona'
- ${{ inputs.persona }}
- '--prompt'
- ${{ inputs.prompt }}# ... add logic to handle prompt vs prompt-file and other args ...