DevLab

DevLab is a command-line tool that turns written software requirements into reviewed changes through a sequence of bounded agent sessions. It coordinates planning, implementation, review, and integration, keeping the work and its history in your project's Git repository.

DevLab is intended for projects whose scope spans many agent sessions and needs consistent decisions, explicit review, and a way to recover after interruptions. It works with new and existing repositories. DevLab itself runs on Python; target projects can use Python, Rust, Go, C, C++, or mixed toolchains.

First-workflow tutorial · Documentation · Project vision

How it works

You supply the requirements, configure the coding agents and project tools, and review the results. DevLab manages the workflow:

1. Plan: an architect develops the design; a planner breaks the work into tasks and milestones.
2. Implement and review: a developer works on one task. DevLab runs its configured validation, then a separate reviewer session checks the work. Requested changes return to a developer.
3. Integrate: an integrator checks completed milestones. Architecture review records remaining gaps for corrective work.

Each agent session has one role. Specifications, plans, tasks, findings, and handoffs live under .devlab/ in the target repository, alongside the software being built. DevLab commits accepted session results and uses the recorded progress to choose the next action. Sessions can request research or stop for a decision from you when needed.

You can inspect the files and Git history between runs and continue from the recorded state after a stop. Progress does not depend on retaining a conversation with an agent.

You choose the coding-agent CLI and can configure different providers or models for different roles. DevLab supplies the workflow and role prompts; the target project supplies its tooling and validation commands.

Project status

DevLab is pre-1.0. Its CLI, configuration, and workspace formats remain provisional until the 1.0 compatibility freeze. It is distributed as a Python package to provide the CLI; its Python modules are not a supported library API. See the release policy for compatibility expectations.

Automated tests and scripted workflow evaluations cover the core workflow. Live-agent evaluation coverage is still developing; see the evaluation evidence. Start with a disposable project and review the generated changes before relying on them.

Install

You need:

• Python 3.12 or newer and uv.
• Git on PATH, with a name and email configured for commits.
• An installed coding-agent CLI with access to its provider to run the workflow.
• The build and test tools required by your target project. DevLab does not install missing host tools.

Install DevLab from PyPI:

uv tool install devlab
devlab --version

For a reproducible installation, pin a version with uv tool install "devlab==0.1.2". You can also install an immutable Git tag or commit with uv tool install "git+https://github.com/djulich/devlab.git@v0.1.2", or a local checkout with uv tool install /path/to/devlab-checkout. TestPyPI is used only for publication rehearsals. For an editable development installation, see Contributing.

Run your first workflow

The first-workflow tutorial provides a complete specification, agent configuration, and commands for building a small Python CLI. The outline below shows the same setup process for a new project. For an existing repository, follow Adopt an existing project.

1. Initialize a target workspace

Create a directory for the software you want to build, then initialize DevLab inside it:

mkdir my-project
cd my-project
devlab init

Initialization is language-neutral. For a new project with conventional tooling preferences, use devlab init --template python instead; starters also exist for Rust, Go, C, and C++. Templates provide initial tooling configuration, not the application itself.

devlab init initializes Git when needed and commits non-ignored files. Before using it in a populated directory, make sure .gitignore excludes secrets, local configuration, caches, and generated artifacts.

2. Describe the work and configure the tools

Edit these files in the target workspace:

• .devlab/specs/system/README.md: the required behavior and acceptance criteria.
• .devlab/config/agents.toml: how DevLab starts your installed coding agent.
• .devlab/config/tooling.md and .devlab/config/profiles/: the project's tooling policy, validation commands, and any environment setup.

The tutorial supplies a working example. For other providers or role overrides, see Agent configuration.

Review executable configuration before running it. DevLab executes agent, validation, and environment commands from the target repository. It does not sandbox these commands; permissions and isolation come from your agent provider and execution environment. Only authorize configuration you trust.

Commit your setup changes. DevLab requires a clean working tree before starting agent sessions:

git add .devlab/specs .devlab/config
git commit -m "Configure DevLab project"

3. Check the setup and start a bounded run

devlab doctor
devlab trust executable-config
devlab agent-smoke-test
devlab continue

doctor checks configuration and workflow state without changing them. The trust command shows the executable configuration and asks for approval; the smoke test invokes the provider to check that it works. Resolve any reported setup problems before continuing.

On a fresh project, devlab continue stops after planning, before implementation. Inspect the generated plans, then run it again to begin implementation. Each invocation runs at most 20 sessions by default, providing regular checkpoints to review progress. Use --max-sessions to adjust this limit.

Both the smoke test and workflow sessions consume usage from your configured provider; a session limit does not cap provider billing.

Inspect and continue

After a run, read its summary and inspect the generated files and Git commits. These four commands cover routine operation:

The first three commands are read-only. continue selects planning, implementation, review, integration, or recovery as needed. Reaching the session limit is a checkpoint, not completion. Resolve any reported blockers or requests for your decision, then run the same continuation command again.

See the operator guide for clarification, recovery, unattended operation, and advanced commands. Use devlab --help and devlab COMMAND --help for the full command reference.

Documentation and examples

• Documentation index: guides, architecture, evaluations, and project direction.
• How-to guides: adopt an existing project, fix a bug, revise a specification, or recover an interrupted workflow.
• Runtime prerequisites and managed test services: configure validation environments and workspace-owned services.
• First-workflow demo: a resettable presentation of the tutorial with independent result checks.

Contributing and license

See Contributing for development setup and contribution guidelines. Report bugs through GitHub issues and security vulnerabilities privately through the security policy.

DevLab is licensed under the Apache License 2.0.