sweteam

┌─────────────────┐
│    ◉       ◉    │
│    ─────────    │
└─────────────────┘

sweteam

Autonomous coding agent orchestrator — turns high-level goals into PR'd code.
It is not another coding agent. It orchestrates the ones you already have.

Quick Start · How It Works · Commands · Configuration · Contributing

Why sweteam?

Real software isn't built by a single person typing in a terminal. It's built by teams — a tech lead breaks down the work, engineers pick up tasks, reviewers catch mistakes, and the whole thing ships through a structured process. That's what makes production code robust.

sweteam brings that same discipline to AI coding agents:

              How a real engineering team works
              ─────────────────────────────────

 ┌───────────┐    You describe what you want. The planner
 │  You      │    asks questions, proposes an architecture,
 │  (PM)     │    and breaks it into scoped tasks — just like
 └─────┬─────┘    a tech lead running a planning session.
       │
       ▼
 ┌────────────┐   The planner decomposes your goal into small
 │  Planner   │   tasks with acceptance criteria, dependency
 │ (Tech Lead)│   order, and file-level scope. You review
 └─────┬──────┘   and refine before anything gets built.
       │
       │  @build
       ▼
 ┌───────────┐    Each task is assigned to a coding agent on
 │  Coders   │    its own branch. Independent tasks run in
 │(Engineers)│    parallel — like engineers on a team working
 └─────┬─────┘    on separate features simultaneously.
       │
       ▼
 ┌───────────┐    A separate agent reviews each task's diff
 │ Reviewer  │    against its acceptance criteria. If the
 │  (Senior) │    review fails, the coder automatically
 └─────┬─────┘    retries — this loop repeats until the
       │          reviewer is satisfied or the max cycle
       │          limit is reached, just like a real senior
       │          engineer blocking a PR until it's right.
       │
       ▼
 ┌───────────┐    Approved tasks are merged, the branch is
 │  Git + PR │    pushed, and a PR is opened. The session
 │  (CI/CD)  │    stays open — give feedback, agents iterate
 └─────┬─────┘    on the same PR until you're satisfied.
       │
       ▼
      Done

The key ideas:

Granular task breakdown — your goal is decomposed into small, scoped tasks with explicit acceptance criteria, so each agent call has a clear contract
DAG execution — tasks are organized into a dependency graph and dispatched in the correct order, with independent tasks running in parallel
Multi-model review loop — every task is reviewed by a separate agent against its acceptance criteria; failures are retried automatically, just like a real code review cycle
Session persistence — sessions, plans, tasks, diffs, and full conversation history are stored in SQLite; crash, close the terminal, come back tomorrow — nothing is lost
Agent-agnostic — works with Claude Code, Codex CLI, OpenCode, or any custom CLI that reads stdin and writes stdout

sweteam doesn't replace your coding agents. It gives them the same structure that makes real engineering teams ship reliable code.

Web Dashboard

Monitor all your sessions, tasks, and agent output from a browser-based dashboard:

npm run web
# → http://localhost:3847

Session list

Browse all sessions at a glance — status badges, task progress bars, and timestamps.

Session detail

Click into any session to see the full conversation timeline, task breakdown, progress ring, and PR link.

Terminal REPL

The CLI also includes an interactive REPL with agent output streaming in real time:

▶ Coder ─ task-001: Add ThemeConfig and color definitions
──────────────────────────────────────────────────────────
│ Creating src/theme/config.ts with color palette...
│ Adding ThemeConfig interface with light/dark variants...
✓ Coder completed

▶ Reviewer ─ task-001: Add ThemeConfig and color definitions
──────────────────────────────────────────────────────────
│ Reviewing diff against acceptance criteria...
│ All criteria met. Approving.
✓ Reviewer completed

Features

Session-based — every interaction lives in a persistent session with full history
Zero config — discovers installed CLIs automatically, uses their existing auth
Human-in-the-loop planning — chat with the planner, refine the plan, then go hands-off
Parallel execution — independent tasks run concurrently across multiple agents
Review loop — built-in code review with configurable retry cycles
Feedback iterations — session stays open; you give feedback, agents iterate on the same PR
Live attach — re-enter any session and see agent output streaming in real time
Git native — all git/GitHub operations via git and gh CLI directly
Image input — attach images to your session and forward them to underlying CLI agents
Pluggable agents — supports Claude Code, Codex CLI, OpenCode, or any custom CLI

Prerequisites

You need at least one coding CLI installed:

CLI	Install
Claude Code	`npm install -g @anthropic-ai/claude-code`
Codex CLI	`npm install -g @openai/codex`
OpenCode	`go install github.com/opencode-ai/opencode@latest`

Plus these required tools:

git — version control
gh — GitHub CLI (authenticated via gh auth login)
Node.js — v20+

Installation

From npm

npm install -g sweteam

From source

git clone https://github.com/SiluPanda/sweteam.git
cd sweteam
npm install
npm run build
npm link

Quick Start

1. Initialize

sweteam init

Auto-discovers your installed CLIs and generates ~/.sweteam/config.toml:

✓ Found claude (Claude Code v1.x)
✓ Found codex (Codex CLI v0.x)
✗ opencode not found
✓ Found gh (GitHub CLI v2.x)
✓ Found git (v2.43)
Generated ~/.sweteam/config.toml

2. Create a session

sweteam create myrepo

Or launch the interactive REPL and create from there:

sweteam
sweteam> /create myrepo

This will:

Resolve myrepo to your GitHub username (e.g. YourName/myrepo)
Clone the repo (or fetch latest if already cloned)
Create a working branch
Enter the planning chat

3. Plan interactively

You're now chatting with the planner agent. Describe your goal, ask questions, refine the approach:

crawlgator-ui> Add dark theme with system preference detection and a Ctrl+T toggle

▶ Planner ─ s_a1b2c3d4: Add dark theme
────────────────────────────────────────
│ I'll break this down into 6 tasks:
│
│ task-001: Add ThemeConfig and color definitions
│ task-002: Implement system preference detection
│ task-003: Create dark theme preset
│ ...
│
│ Type @build when you're ready.
✓ Planner completed

crawlgator-ui> @build

4. Watch it build

sweteam decomposes the plan into tasks, dispatches them to coding agents, reviews each result, and merges into the session branch — all autonomously.

Plan finalized. Starting autonomous build...

Found 6 tasks:

  task-001  Add ThemeConfig and color definitions
  task-002  Implement system preference detection
  task-003  Create dark theme preset (depends on: task-001)
  task-004  Create light theme preset (depends on: task-001)
  task-005  Wire theme into TUI render paths (depends on: task-002, task-003, task-004)
  task-006  Add runtime theme toggle (depends on: task-005)

▶ Coder ─ task-001: Add ThemeConfig and color definitions
──────────────────────────────────────────────────────────
│ Creating src/theme/config.ts...
│ ...
✓ Coder completed

▶ Reviewer ─ task-001: Add ThemeConfig and color definitions
──────────────────────────────────────────────────────────
│ Reviewing diff against acceptance criteria...
✓ Reviewer completed

Build complete.

  ✓ task-001  Add ThemeConfig and color definitions
  ✓ task-002  Implement system preference detection
  ✓ task-003  Create dark theme preset
  ✓ task-004  Create light theme preset
  ✓ task-005  Wire theme into TUI render paths
  ⚠ task-006  Add runtime theme toggle — FAILED

PR: https://github.com/YourName/myrepo/pull/42

Review the PR and type @feedback with any changes needed.

5. Give feedback

crawlgator-ui> @feedback The dark theme colors are too muted. Make the accent brighter (#00BFFF).

Agents pick up your feedback, iterate, and push updates to the same PR.

6. Re-enter a session

Come back later and pick up where you left off. If agents are still running, you'll see their output stream live:

sweteam enter s_a1b2c3d4

Entered session s_a1b2c3d4 (YourName/myrepo)
  Goal:   Add dark theme with system preference detection
  Status: building

Attaching to live build output... (press Enter to detach)

▶ Coder ─ task-005: Wire theme into TUI render paths
──────────────────────────────────────────────────────────
│ Integrating theme provider into the component tree...

Commands

Top-level commands

Command	Description
`sweteam`	Launch interactive REPL
`sweteam web`	Start the web dashboard (port 3847)
`sweteam init`	Auto-discover CLIs and generate config
`sweteam create [repo]`	Create a new session
`sweteam list`	List all sessions
`sweteam enter <session_id>`	Re-enter an existing session
`sweteam show <session_id>`	Show detailed session status
`sweteam stop <session_id>`	Stop a session
`sweteam delete <session_id>`	Delete a session

In-session commands

Once inside a session, use @ commands:

Command	Description
`@build`	Finalize plan and start autonomous coding
`@status`	Show task progress dashboard
`@plan`	Re-display the current plan
`@feedback <text>`	Give feedback on completed work (triggers new iteration)
`@watch`	Re-attach to live agent output
`@diff`	Show cumulative diff
`@pr`	Show the PR link
`@tasks`	List all tasks with statuses and review info
`@ask`	Ask the architect about the development process
`@cancel`	Cancel the current planner run (session stays active)
`@image <path>`	Attach image file(s) to pass to the underlying CLI agent
`@images`	List attached images (`@images clear` to remove all)
`@stop`	Stop this session and return to REPL
`@help`	Show available commands

Any other text is sent directly to the planner for conversation.

REPL commands

Inside the interactive REPL, use / commands:

Command	Description
`/create [repo]`	Start a new session
`/list`	See all sessions
`/enter <id>`	Resume a session
`/show <id>`	Inspect a session
`/stop <id>`	Stop a session
`/delete <id>`	Delete a session
`/init`	Re-run CLI discovery
`/help`	Show help
`/exit`, `/quit`	Quit

CLI flags

sweteam --coder codex          # Override coder agent
sweteam --reviewer claude-code # Override reviewer agent
sweteam --planner codex        # Override planner agent
sweteam --parallel 5           # Override max parallel tasks
sweteam --config ./custom.toml # Use custom config file
sweteam --image photo.png      # Attach image file(s) to session

List filters

sweteam list --status building    # Filter by status
sweteam list --repo myrepo        # Filter by repo name

How It Works

Architecture

┌──────────────────────────────────────────────────────────┐
│                       sweteam CLI                        │
│                                                          │
│  ┌──────────┐  ┌──────────────┐  ┌────────────────────┐  │
│  │ Session  │  │   Planner    │  │  Orchestrator      │  │
│  │ Manager  │  │  (chat mode) │  │  (autonomous)      │  │
│  └──────────┘  └──────────────┘  └────────────────────┘  │
│                                                          │
│  ┌────────────────────────────────────────────────────┐  │
│  │          Agent Adapter Layer                       │  │
│  │ ┌────────────┐ ┌──────────┐ ┌────────────────────┐ │  │
│  │ │ Claude Code│ │ Codex CLI│ │ OpenCode / Custom  │ │  │
│  │ └────────────┘ └──────────┘ └────────────────────┘ │  │
│  └────────────────────────────────────────────────────┘  │
│                                                          │
│  ┌──────────────────────┐  ┌──────────────────────────┐  │
│  │  SQLite + Drizzle    │  │  git + gh CLI (native)   │  │
│  │  (session store)     │  │  (branches, PRs, commits)│  │
│  └──────────────────────┘  └──────────────────────────┘  │
└──────────────────────────────────────────────────────────┘

Session lifecycle

                    /create
                       │
                       v
        ┌──────────────────────────┐
        │        planning          │ <── chat with planner
        └────────────┬─────────────┘
                     │ @build
                     v
        ┌──────────────────────────┐
        │        building          │ <── agents code + review
        └────────────┬─────────────┘
                     │
                     v
        ┌──────────────────────────┐
        │    awaiting_feedback     │ <── PR created, user reviews
        └────────────┬─────────────┘
                     │ @feedback
                     v
        ┌──────────────────────────┐
        │        iterating         │ <── agents apply feedback
        └────────────┬─────────────┘
                     │
                     v
              awaiting_feedback ─── (loops until satisfied)
                     │
                     │ /stop
                     v
        ┌──────────────────────────┐
        │         stopped          │
        └──────────────────────────┘

Task execution pipeline

Plan — the planner agent decomposes your goal into tasks with dependencies
DAG — tasks are organized into a dependency graph
Dispatch — independent tasks run concurrently (up to max_parallel)
Code — each task is assigned to a coding agent on its own git branch
Review — a reviewer agent checks the diff against acceptance criteria
Fix loop — if review finds issues, the coder retries (up to max_review_cycles)
Merge — approved tasks are squash-merged into the session branch
PR — the session branch is pushed and a GitHub PR is created

Configuration

Config lives at ~/.sweteam/config.toml. Generated by sweteam init.

[roles]
planner = "claude-code"       # Which CLI generates the plan
coder = "claude-code"         # Which CLI writes code
reviewer = "claude-code"      # Which CLI reviews code

[execution]
max_parallel = 3              # Concurrent coding agents
max_review_cycles = 3         # Review/fix loops before escalating
branch_prefix = "sw/"         # Prefix for all branches

[git]
commit_style = "conventional" # conventional | simple
squash_on_merge = true

[agents.claude-code]
command = "claude"
args = ["-p"]

[agents.codex]
command = "codex"
args = ["-q"]

[agents.opencode]
command = "opencode"
args = ["--non-interactive"]

Custom agents

Any CLI that accepts a prompt on stdin and writes output to stdout can be used as an agent:

[agents.my-agent]
command = "my-coding-tool"
args = ["--mode", "autonomous"]
prompt_via = "stdin"          # stdin | arg | file
output_from = "stdout"        # stdout | file

Then reference it in your roles:

[roles]
coder = "my-agent"

Data storage

All data is stored locally:

~/.sweteam/
├── sweteam.db          # SQLite database (sessions, tasks, messages)
├── config.toml         # Global configuration
├── logs/               # Agent output logs (for live attach)
│   └── s_a1b2c3d4.jsonl
└── repos/              # Cloned repositories
    └── YourName--myrepo/

No API keys stored — coding CLIs manage their own authentication
No network calls — sweteam itself makes zero API requests; only the underlying agents and git/gh do
Full audit trail — every prompt, response, and system event is stored per session

Development

git clone https://github.com/SiluPanda/sweteam.git
cd sweteam
npm install

# Run in dev mode (no build step)
npm run dev

# Run with subcommands
npm run dev -- create myrepo

# Run tests
npm test

# Build
npm run build

# Link globally for testing
npm link

Project structure

src/
├── index.ts                 # CLI entry point (Commander.js)
├── repl/                    # Interactive REPL loop
├── session/                 # Session manager, state machine, agent log
├── planner/                 # Planner agent and plan parser
├── orchestrator/            # Task runner, reviewer, build/feedback handlers
├── adapters/                # Agent adapters (claude-code, codex, opencode, custom)
├── commands/                # CLI subcommands (create, list, enter, etc.)
├── config/                  # Config loader and GitHub auth
├── git/                     # Git and GitHub CLI wrappers
├── ui/                      # Terminal UI (banner, prompt, agent panel, sidebar, markdown, theme)
├── web/                     # Web dashboard (HTTP server + single-page UI)
├── db/                      # SQLite schema and client (Drizzle ORM)
├── utils/                   # Utility functions (time formatting)
└── __tests__/               # Test suite

Tech stack

Component	Choice
Language	TypeScript (ESM, Node.js 20+)
ORM	Drizzle
Database	SQLite via better-sqlite3
CLI framework	Commander.js
Terminal UI	Custom (chalk, gradient-string, raw-mode prompt)
Git	`git` + `gh` CLI (child process)
IDs	nanoid
Config	TOML
Tests	Vitest

Contributing

Contributions are welcome. Please open an issue first to discuss what you'd like to change.

# Fork and clone
git clone https://github.com/your-name/sweteam.git
cd sweteam
npm install

# Create a branch
git checkout -b feat/my-feature

# Make changes, run tests
npm test

# Submit a PR

License

MIT

Name		Name	Last commit message	Last commit date
Latest commit History 119 Commits
.github/workflows		.github/workflows
db		db
docs		docs
drizzle/migrations		drizzle/migrations
src		src
.gitignore		.gitignore
.npmignore		.npmignore
.prettierignore		.prettierignore
.prettierrc		.prettierrc
LICENSE		LICENSE
README.md		README.md
bugbash.md		bugbash.md
drizzle.config.d.ts.map		drizzle.config.d.ts.map
drizzle.config.js		drizzle.config.js
drizzle.config.ts		drizzle.config.ts
eslint.config.js		eslint.config.js
package-lock.json		package-lock.json
package.json		package.json
spec.md		spec.md
tasks.md		tasks.md
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

sweteam

Why sweteam?

Web Dashboard

Session list

Session detail

Terminal REPL

Features

Prerequisites

Installation

From npm

From source

Quick Start

1. Initialize

2. Create a session

3. Plan interactively

4. Watch it build

5. Give feedback

6. Re-enter a session

Commands

Top-level commands

In-session commands

REPL commands

CLI flags

List filters

How It Works

Architecture

Session lifecycle

Task execution pipeline

Configuration

Custom agents

Data storage

Development

Project structure

Tech stack

Contributing

License

About

Topics

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages