An isolated, multi-agent TDD (Test-Driven Development) pipeline controlled via a Telegram bot. It runs in a rootless Podman sandbox and orchestrates official agent CLIs (agy, cursor, claude, or aider) through a configurable pipeline.
-
TDD Workflow: Enforces tests first β production code is only added to satisfy failing tests (Red-Green-Refactor).
-
Pluggable Agent CLI: Select the tool via
AGENT_TOOLin.env. The image installs only that CLI; volume mounts and auth are generated automatically. -
Flexible Git Authentication: HTTPS cloning (
GITHUB_TOKEN) or SSH cloning (dedicated key mounted read-only into the container). -
Multi-Model Orchestration: Configurable TDD pipeline supporting two operational modes:
- β‘ Easy Mode (Default β for standard tasks): Skips the Architect Reviewer validation and sets Code Reviewer reasoning budget to
mediumfor faster execution. - π‘οΈ Hard Mode (for complex/difficult tasks): Runs full 7-step pipeline with Architect Reviewer validation (
gemini-3.1-pro,highreasoning) and Code Reviewer withhighreasoning.
Pipeline Steps:
- Architect (Planning β PLAN):
gemini-3.7-flash, high reasoning, 5m timeout. - Architect Reviewer (Plan Validation β PLAN, Hard mode only):
gemini-3.1-pro, high reasoning, 5m timeout. Validates the plan; aborts the pipeline if flawed or appends notes/observations in append-only mode. - Test Developer (Testing β RED):
gemini-3.7-flash, medium reasoning, 10m timeout. - Developer (Implementation β GREEN):
gemini-3.7-flash, medium reasoning, 10m timeout. - Code Reviewer (Review β PLAN):
gemini-3.7-flash, medium reasoning in Easy mode / high reasoning in Hard mode, 5m timeout. - Refactoring Developer (Refactoring β REFACTOR):
gemini-3.7-flash, medium reasoning, 10m timeout. - GitOps (Documentation and PR):
gemini-3.7-flash, low reasoning.
How each
AGENT_TOOLuses the config above:Tool CLI invoked Models / reasoning agyagy --model "Gemini β¦ (Budget)"Per-step model and reasoning from the pipeline cursoragent -p β¦ --model cursor-grok-4.5-high --trust --forceAlways cursor-grok-4.5-high; pipeline model/reasoning ignoredclaudeclaude --print --model β¦ --effort β¦Gemini slugs mapped to Claude aliases; reasoning β --effortaideraider --model β¦ --message β¦Per-step modelpassed to--model; reasoning ignored - β‘ Easy Mode (Default β for standard tasks): Skips the Architect Reviewer validation and sets Code Reviewer reasoning budget to
- Podman and
podman composeon the host. - A Telegram Bot Token (@BotFather).
- Your Telegram Chat ID (@userinfobot).
- Git credentials (one of):
- GitHub Personal Access Token (
GITHUB_TOKEN), or - Passphrase-less SSH key (e.g.
~/.ssh/id_aegis) added to GitHub.
- GitHub Personal Access Token (
cp .env.example .envEdit .env:
GITHUB_TOKEN=your_github_token_here # Leave blank if using SSH
TELEGRAM_BOT_TOKEN=12345:AABBBCCC
TELEGRAM_CHAT_ID=your_chat_id_here
DEFAULT_REPO=owner/repo # Optional default repository
AGENT_TOOL=cursor # agy | cursor | claude | aiderChanging AGENT_TOOL requires a rebuild: make build.
AGENT_TOOL |
Authentication | Session paths mounted into the container |
|---|---|---|
agy |
agy login on the host |
~/.config/antigravity, ~/.gemini/*, ~/.antigravity |
claude |
claude auth login on the host |
~/.claude, ~/.claude.json |
cursor |
CURSOR_API_KEY in .env or agent login on the host |
~/.cursor, ~/.config/Cursor |
aider |
API keys in .env (provider-specific) |
β |
make build / make up reads AGENT_TOOL from .env, renders compose.tool.yml, and passes the tool as a Containerfile build arg so only that CLI is installed in the image.
Option A β API key (recommended for containers)
No Cursor CLI required on the host. Works with an active Cursor subscription.
- Create a User API Key at cursor.com/dashboard/integrations.
- Add to
.env:AGENT_TOOL=cursor CURSOR_API_KEY=your_key_here
- Build and start:
make build
Option B β Host session login
- Install and log in on the host (credentials are bind-mounted into the container):
curl -fsSL https://cursor.com/install | bash agent login - Set
AGENT_TOOL=cursorin.envand runmake build.
The pipeline invokes agent --print "<prompt>" --model cursor-grok-4.5-high --trust --force. Pipeline model/reasoning fields are ignored for Cursor. PR reviews use --mode ask instead of --force (see PR review).
Verify inside the running container:
podman exec agent_workspace agent --print "say hi" --model cursor-grok-4.5-high --trust --force- Install and log in on the host (credentials are bind-mounted into the container):
npm install -g @anthropic-ai/claude-code claude auth login
- Set
AGENT_TOOL=claudein.envand runmake build.
The pipeline invokes claude --print --model <alias> --effort <budget> --dangerously-skip-permissions "<prompt>". Gemini pipeline slugs map to Claude aliases (gemini-3.7-pro/gemini-3.1-pro β opus, gemini-3.7-flash/gemini-3.5-flash β sonnet); reasoning_budget maps to --effort. PR reviews use --permission-mode plan instead of --dangerously-skip-permissions.
If you use SSH instead of GITHUB_TOKEN:
ssh-keygen -t ed25519 -N "" -f ~/.ssh/id_aegisAdd ~/.ssh/id_aegis.pub to GitHub. compose.yml mounts the key read-only at /root/.ssh/id_aegis.
make build # First run or after changing AGENT_TOOL
make up # Subsequent startsThis starts only the agent container by default. The PostgreSQL database (agent_postgres) is opt-in β start it when a task needs a database:
make db-up # Start the database container
make db-down # Stop the database containerThe agent connects via postgresql://admin:admin@db:5432/appdb when the database is running.
Or manually:
python3 scripts/render_compose_overlay.py
podman compose --env-file .env -f compose.yml -f compose.tool.yml up -d --build
podman compose --env-file .env -f compose.yml -f compose.tool.yml --profile db up -d db # optionalSend /start in your Telegram chat. The bot confirms the system is online.
The workspace is isolated inside the container β specify which repository to clone.
Explicit repository prefix (recommended):
owner/repository_name: Create a User entity with SQLAlchemy. Write Pytest tests for persistence and email validation.
With full URL:
https://github.com/owner/repository_name.git: Create a User entity...
Without prefix (uses DEFAULT_REPO from .env, or the last repository from session memory):
Create a User entity using SQLAlchemy. Write Pytest tests to verify database persistence.
| Command | Description |
|---|---|
make build |
Render compose.tool.yml, build image, start agent container |
make up |
Render overlay and start agent container |
make down |
Stop the stack (agent and database, if running) |
make db-up |
Start the optional PostgreSQL database container |
make db-down |
Stop the PostgreSQL database container |
make restart |
Re-render overlay and restart |
make logs |
Follow agent container logs |
make status |
Show container status |
make test |
Run test suite with coverage (β₯99%) |
Project configuration lives in pyproject.toml (pytest and coverage settings).
Install test dependencies on the host:
pip install -e ".[test]"
make testOn failure, state is persisted to ~/.config/aegis-phalanx/session.json (mounted from the host).
Send demands directly via Telegram:
- Easy Mode (Default β skips Architect Reviewer, medium review effort):
owner/repo: add login endpoint[easy] owner/repo: add login endpointowner/repo: fΓ‘cil: add login endpoint
- Hard Mode (Includes Architect Reviewer plan validation & high review effort):
[hard] owner/repo: refactor authentication architectureowner/repo: [hard] refactor authentication architectureowner/repo: difΓcil: refactor authentication architectureowner/repo: --hard refactor authentication architecture
/startβ Show help and mode selection instructions./continueor/resumeβ Resume from the first failed/incomplete step./statusβ Show active mode, step statuses, repository, branch, and demand./reviewβ Review an existing GitHub PR (see PR review)./stopβ Cancel a running pipeline./clearβ Delete session memory.
The bot classifies intent using the active AGENT_TOOL CLI:
- "continue", "resume", "continuar a tarefa" β resume flow
- "status", "memΓ³ria" β show session details
- Anything else β new demand
Model quota usage (/status) is shown only when AGENT_TOOL=agy.
Review an existing GitHub pull request without modifying the repository or posting comments. The bot clones the repo, checks out the PR branch, pre-fetches metadata and diff via gh, and runs a single review step with the active AGENT_TOOL.
/review owner/repo#123
Supported reference formats:
| Format | Example |
|---|---|
owner/repo#N |
/review acme/api#42 |
owner/repo:N or owner/repo N |
/review acme/api:42 |
| GitHub PR URL | /review https://github.com/acme/api/pull/42 |
| PR number only | /review 42 (requires DEFAULT_REPO in .env) |
GITHUB_TOKENβ required for HTTPS clones (same as the TDD pipeline).ghauth β mounted from~/.config/ghon the host; used to check out the PR and fetch context before the agent runs.AGENT_TOOLβ selects which CLI performs the review (rebuild after changing).
| Tool | Review invocation | Notes |
|---|---|---|
agy |
agy --model "Gemini 3.7 Flash (High)" β¦ |
Per-step model and reasoning from agents/review_pipeline.py |
cursor |
agent --print --mode ask --model cursor-grok-4.5-high --trust "<prompt>" |
Read-only ask mode; PR context is pre-fetched so the agent does not need gh |
claude |
claude --print --permission-mode plan --model β¦ --effort β¦ |
Read-only plan mode; Gemini slugs mapped to Claude aliases |
aider |
aider --model β¦ --message β¦ |
Per-step model passed to --model |
The review text is returned to Telegram only β no commits, file changes, or GitHub comments.
telegram_listener.py # Telegram bot composition root (handlers + wiring)
orchestrator/ # Pipeline, review, git, process, and parsing helpers
agents/
adapters/ # CLI adapters (agy, cursor, claude, aider)
pipeline.py # TDD step definitions
review_pipeline.py # PR review step definition
registry.py # Agent factory
tool_specs.py # Per-tool install commands and volume mounts
scripts/
install_agent_tool.py # Containerfile install helper
render_compose_overlay.py # Generates compose.tool.yml from .env