devage 0.1.11

Local human-in-the-loop multi-agent development environment

devage — Developer Agency

Local, human-in-the-loop multi-agent development environment.

A developer orchestrates a team of autonomous AI agents. Each agent runs as a long-lived Docker container daemon, creates a per-task Git branch, commits progress after every workflow step, and picks up tasks from a shared Kanban board backed by SQLite. Tasks are authored as Markdown files — the files are the source of truth, the database is a queryable index. Agents execute YAML-defined workflows entirely inside the container — calling claude -p for LLM steps, running bash validation, and auto-committing completed work — while the human reviews and approves from a VS Code dashboard.

Requirements

Dependency	Version	Notes
Python	3.9+	Required for the CLI (pip install devage)
Docker	24+	Required to build and run agent containers
Git	2.38+	Required for per-agent worktrees and branch management
VS Code	1.85+	Required for the dashboard extension

Python virtual environment (optional but recommended)

The VS Code extension can install the CLI into your project's virtual environment so it is isolated from your system Python. Create one before opening the dashboard:

python -m venv .venv
# macOS / Linux
source .venv/bin/activate
# Windows
.venv\Scripts\activate

The extension detects .venv or venv in the workspace root automatically and offers to install there. If no virtual environment is found it falls back to a global pip install --user.

---

Repository Layout

devage/
├── .devage/                  # Local project config and runtime state
│   ├── agents/               #   Per-agent Dockerfiles + devage.whl build artefact
│   ├── milestones/           #   MILESTONE-NNN_<slug>.md files from the roadmap builder
│   ├── state/                #   Wizard state (roadmap cursor, resume support)
│   ├── tasks/                #   Task .md files (TASK-NNN_slug.md) — source of truth
│   ├── team.yaml             #   Agent definitions
│   ├── worktrees/            #   Per-agent git worktrees
│   └── *.db                  #   SQLite database (queryable task/agent index)
├── cli/                      # Python orchestrator (compiled to standalone binary)
│   └── devage/
│       ├── cli/              #   CLI entry point, command modules (init/agent/task), ProjectContext
│       ├── engine/           #   Workflow engine, workers, task/milestone managers
│       ├── database/         #   SQLAlchemy ORM models, agent repository, session management
│       ├── models/           #   Pydantic config validation
│       └── orchestrator/     #   Docker container + Git worktree lifecycle
├── vscode-extension/         # TypeScript/React VS Code extension (dashboard UI)
└── docs/                     # Architecture and reference documentation

Quickstart

Python CLI

cd cli
pip install -e ".[dev]"

# Set your LLM API key
export ANTHROPIC_API_KEY=sk-ant-...

# First-time setup (interactive wizard)
devage init
# Phase 1 — Workspace scan:    if the project dir has existing code, claude -p
#                               summarises it and seeds the goal interview.
# Phase 2 — Goal interview:    short Q&A → .devage/project_goal.md
# Phase 3 — Team setup:        validates team.yaml, registers agents in the DB
# Phase 4 — Roadmap builder:   proposes milestones (epics) one at a time;
#                               accept / edit / pause / done
#                               → .devage/milestones/MILESTONE-NNN_<slug>.md
# Phase 5 — DB init:           creates .devage/<project>.db

# Resume a paused roadmap session
devage init --resume-roadmap

# View the Kanban board
devage status

Scripted / CI usage (skip all wizard prompts):

devage init --team-yaml .devage/team.yaml

Working with tasks

Tasks live as Markdown files in .devage/tasks/. The CLI creates them and keeps the database in sync.

# Create a task (prints path of the created .md file)
devage create-task --title "Implement login endpoint" --assignee "backend_dev"
# → .devage/tasks/TASK-001_implement_login_endpoint.md

# Edit the task file directly — add acceptance criteria, adjust assignee, etc.
# Then re-sync the database:
devage sync
# Synced 1 tasks (0 errors)

Starting agents and running tasks

# Build the agent's Docker image and start it as a detached container daemon.
# The container runs the internal poll loop automatically — no second command needed.
devage start-agent tech_lead
# Builds image devage-tech_lead:latest (first run: 1–3 min)
# Starts container: devage-tech_lead
# Agent tech_lead started. Container: devage-tech_lead

# Watch the agent work (optional)
docker logs devage-tech_lead --follow

# Stop the agent
devage stop-agent tech_lead

The container polls every 10 seconds. It resumes its own IN_PROGRESS tasks first (crash recovery), then claims APPROVED tasks. Each AI/bash step is committed to the task's dedicated git branch (git add . && git commit). When the workflow reaches a human_review step the task moves to IN_REVIEW; the human sets the status back to approved in the task's .md file and runs devage sync to resume from where it paused. Task status updates flow back through the shared SQLite database so the VS Code dashboard updates in real time.

Opening a shell in an agent's container

devage shell backend_dev
# Opens: docker exec -it -w /workspace devage-backend_dev /bin/bash
# Type exit or Ctrl+D to return.

Hiring agents

# Fully interactive interview (wizard asks about role, model, workflows, and tools)
devage create-agent

# Pre-fill the role description
devage create-agent --role-hint "A Python backend dev who writes tests first"

The wizard asks which CLI tools and runtimes the agent needs (e.g. nodejs, python3, go, rust, make). It generates a per-agent Dockerfile at .devage/agents/Dockerfile.<agent_id> and writes a team.yaml entry with a tools field. The Dockerfile is built automatically the first time you run devage start-agent.

Build standalone binary

cd cli
./build.sh
./dist/devage --version

VS Code Extension

1. Open the project root in VS Code
2. Run npm install inside vscode-extension/
3. Press F5 to open an Extension Development Host
4. Press Ctrl+Shift+P → devage: Open Dashboard

The dashboard shows the Team Roster and Kanban board. You can:

• Start/stop agents with the ▶ Start and ⏹ Stop buttons
• Open a shell in a running agent's container with >_ Jump In
• Click any task card to open its .md file in the editor
• Add a task with the + button in the Backlog column header
• Hire a new agent with + Hire Agent

Agent cards show real-time status: creating while the Docker image is being built, stopping during shutdown, and the current workflow step (e.g. ↳ ai:gen, ↳ validation:tests) while a task is in progress.

Architecture

Document	Description
docs/architecture.md	System overview, component map, IPC contracts
docs/workflow-engine.md	Workflow YAML schema, execution flow, retry logic
docs/task-files.md	Markdown task files, frontmatter schema, sync engine
docs/cli-reference.md	Full command and flag reference
docs/configuration.md	team.yaml schema, config cascade, init wizard

License

MIT