Getting Started

What is Toban?

Toban is an AI agent orchestration platform that organizes coding agents as a team. You define sprints with tasks, and Toban assigns them to Builder agents that work in isolated git branches. You review and approve or reject each agent's work from a real-time dashboard, keeping humans in control of every change that lands in your codebase.

All workspaces include the full Pro feature set. No credit card required -- sign in with GitHub and start. AI agent usage (Claude Code API credits) is billed separately by Anthropic. A typical task consumes roughly 50K-200K tokens depending on complexity.

This guide walks you through creating your first Toban Project and running AI agents on your codebase.

Prerequisites

• Node.js 20+
• A GitHub account
• Claude Code CLI installed and authenticated: npm install -g @anthropic-ai/claude-code then run claude once to sign in with your Anthropic account

1. Sign Up

Visit toban.dev and sign in with your GitHub account. Toban uses GitHub OAuth -- no separate password required.

2. Create a Project

After signing in, you will be guided through the setup wizard. The Project is not created until you complete the wizard, so you can go back and change settings at any step.

Name Your Project

Give your Project a name and optional description. This appears in the dashboard header and agent prompts.

Connect a GitHub Repository

Enter the GitHub repository URL for your project (e.g., https://github.com/your-org/your-repo). Toban will:

• Clone the repository when agents start
• Create isolated branches for each task
• Auto-merge completed work back to the base branch

You can add additional repositories later in Settings > Repositories.

Choose Your Agent Engine

Select the engine for your worker agents:

Currently, Claude Code is the only fully supported engine. Support for additional engines (Codex, Gemini) exists in the provider system but is not yet production-ready.

Configure Agents

The default setup creates a Manager and a Builder agent. The Manager coordinates sprint planning and task proposals via chat. The Builder implements code changes in isolated git worktrees.

3. Set Your Project Spec

After Project creation, go to the /spec page to write your project specification. This is a free-text document that describes:

• What your project does
• Target users
• Tech stack and architecture
• Key constraints or conventions

The spec is injected into every agent prompt, giving agents the context they need to make good decisions. A well-written spec significantly improves agent output quality.

4. Configure Repositories

Go to Settings > Repositories to register repositories that agents should work with:

• Main repository: The primary codebase (set during wizard)
• Sub repositories: Additional repos agents may need access to
• Access control: Restrict which agent roles can access each repo

5. Install the CLI

The CLI (toban-cli) runs on your local machine and orchestrates agent execution. No global install is needed -- npx downloads the latest version on the fly.

# Install Claude Code CLI (required as the agent engine)
npm install -g @anthropic-ai/claude-code

# Run the Toban CLI (no global install needed)
npx toban-cli@latest start --api-url <URL> --api-key <KEY>

Tip: On the Sprint page, click the "$ run" / "CLI" button in the header to copy the full command with the API URL and key pre-filled for your Project.

CLI Options

--api-url <url>       Toban API base URL (or TOBAN_API_URL env)
--api-key <key>       API key (or TOBAN_API_KEY env)
--working-dir <dir>   Repository root (default: cwd)
--branch <branch>     Base branch (default: main)
--model <model>       AI model for Manager chat
--engine <type>       Agent engine (default: claude-code)
--ws-port <port>      WebSocket port (default: 4000, 0=auto)
--debug               Verbose output (or DEBUG=1 env)

6. Create a Sprint

Back on the Sprint page in the dashboard:

1. Click + Sprint to create a new sprint (starts as Active immediately -- no planning phase)
2. Set a Sprint Goal and optional Deadline (click next to the phase stepper)
3. Open the Chat Panel and ask the Manager to propose tasks (e.g., "Propose tasks for this sprint")
4. The Manager analyzes your project spec and backlog, then proposes tasks as interactive cards
5. Click Sprint or Backlog on each card to add to the current sprint or save for later
6. Adjust priorities and assignments on the Kanban board if needed

You can also create tasks manually by clicking Add Task on the sprint board.

Tips for good task descriptions:

• Be specific: "Add user login with GitHub OAuth" not "Add auth"
• Include acceptance criteria when possible
• Reference relevant files or documentation

7. Run Agents

Once the sprint has tasks and the CLI is connected, agents start automatically:

• Tasks owned by agent roles (builder) are automatically picked up by the CLI
• The CLI transitions them from todo to in_progress and spawns the agent
• Tasks owned by user are never auto-started -- those are for you
• Watch agent progress in the Terminal Panel (tool use, file edits, bash commands)

The CLI handles the full lifecycle:

1. Creates an isolated git worktree for the agent
2. Injects agent memories, ADRs, and task context into the prompt
3. Spawns the Claude Code CLI process
4. Monitors progress and streams activity to the Dashboard via WebSocket
5. On completion: merges the agent's branch to main, pushes to remote, generates structured review report

Important: The CLI auto-merges completed work to main, but the task moves to Review status -- not Done. You must explicitly Approve or Reject every task before it is marked as complete. Rejected tasks go back to the agent with your feedback. Nothing is considered "done" without your approval.

>

This trunk-based workflow is the current default. Support for other branching strategies (e.g. GitHub Flow with pull requests) is planned.

8. Review Completed Work

When an agent finishes a task, it moves to Review status on the sprint board:

1. Click the task card to expand the Structured Review Report (requirement match, code quality, test coverage, risks, verdict)
2. Click Approve to mark as done, or Reject with feedback (the agent will rework the task)
3. Rejected tasks go back to the agent with your feedback attached

9. Track Progress

• Sprint Board shows real-time task status via WebSocket (no reload needed)
• Analytics page has Velocity charts, Burndown, Daily Activity, and Agent contribution
• Sprint Goal and Deadline countdown are visible in the sprint header

Prompt Transparency

Want to see exactly what instructions your agents receive? Go to Agents > Prompts in the sidebar to preview the full prompt for any agent role. The preview shows all injected content:

• Role description and security rules
• Project Spec (vision, tech stack, constraints)
• ADR summaries
• Task-specific instructions

This lets you verify and tune the prompt before agents start working. The preview is also available via the API: GET /api/v1/agents/:name/prompt-preview.

Tips: Working with Claude Code Directly

The dashboard chat (Manager) is useful for quick task proposals and sprint management. For deeper work -- architecture discussions, debugging, code reviews, strategic planning -- use Claude Code CLI directly in your terminal.

To give Claude Code full context about your Toban project, feed it the documentation:

Read https://app.toban.dev/llms-full.txt

Combined with your project's CLAUDE.md, this gives Claude Code everything it needs to act as your senior engineering partner while Toban handles the sprint management and agent orchestration.

Next Steps

• Architecture Guide -- How Toban works under the hood
• Setup Guide -- Detailed setup and configuration reference
• ADR Guide -- Architecture Decision Records for agent governance
• Error Reference -- Error codes and troubleshooting
• Security Guide -- Security model and guarantees