Team Agent Platform

Local-first execution for Codex- and Claude-powered agent teams on real GitHub repositories.

Screenshots • Architecture • Quick Start • Documentation

_{From repository selection and diagnostics to live runtime sessions, recovery-aware execution, and draft PR delivery.}

Team Agent Platform is not a hosted public catalog or social discovery product. The current MVP is a self-hosted control plane plus a host execution layer that runs authenticated local tools such as git, gh, codex, and claude.

Screenshots

Open the full screenshot gallery

Architecture At A Glance

The system has two main layers:

• Control Plane: Next.js frontend, FastAPI backend, PostgreSQL, Redis.
• Host Execution Layer: Host Executor, codex, claude, gh, git, PTY or tmux, and local workspaces.

flowchart LR
    U[User in Browser] --> W[Next.js Frontend]
    W --> B[FastAPI Backend]
    B --> DB[(PostgreSQL)]
    B --> R[(Redis)]
    B --> HX[Host Executor]
    HX --> PTY[PTY / tmux]
    HX --> GT[git]
    HX --> GH[gh]
    HX --> CX[codex]
    HX --> CL[claude]
    HX --> WS[Local Workspace]
    GT --> GHub[GitHub]
    GH --> GHub

Loading

The browser talks to the backend. The backend orchestrates runs and stores state. The host executor runs in the host user context, where git, gh, and the selected runtime CLI are already installed and authenticated.

See the deeper architecture documents here:

• Architecture Overview
• Runtime Boundary RFC
• Run Resume and Recovery
• Live-Fire Validation Plan

Run Flow

At a high level, one run goes through these stages:

1. create a run from the UI;
2. prepare a workspace;
3. clone the repository and create a working branch;
4. materialize the runtime bundle and TASK.md;
5. start the selected runtime in the host execution layer;
6. stream terminal output and run events;
7. clean temporary runtime files from the workspace;
8. create a commit when the runtime produced repository changes;
9. require the runtime to finalize commit, push, and draft PR from the prepared workspace;
10. fail the run if the runtime exits without fully finishing SCM delivery.

For Codex-backed runs, the normal launch flow now fixes the root session sandbox to danger-full-access. The runtime owns SCM finalization, so it must be able to write .git, push the working branch, and create the draft PR from the prepared workspace.

If the host executor or transport is interrupted, the platform supports resume and auto-recovery for recoverable sessions.

Quick Start

Fastest Way To Launch Everything

cp .env.example .env
./scripts/dev/up.sh
./scripts/setup/host-executor-local.sh
tmux new-session -d -s tap-host-executor 'cd /absolute/path/to/this/repo && HOST_EXECUTOR_RELOAD=0 ./scripts/dev/run-host-executor.sh'

Use ./scripts/dev/up.sh --build only when Dockerfiles or dependency manifests changed.

Then open:

• frontend: http://localhost:3000
• backend docs: http://localhost:8000/docs
• diagnostics: http://localhost:3000/diagnostics
• runs: http://localhost:3000/runs
• repositories: http://localhost:3000/repos

On a clean install, opening the frontend for the first time now redirects to /setup. That first-run screen lets you:

• create the first admin account;
• choose whether self-registration stays open after setup;
• decide whether to seed the starter Fullstack Delivery Squad team and its base agents.

To stop everything:

tmux kill-session -t tap-host-executor || true
./scripts/dev/down.sh

To inspect the host executor directly:

tmux attach -t tap-host-executor

Step-By-Step Startup

1. Create a local environment file:

cp .env.example .env

2. Start the control plane:

./scripts/dev/up.sh

If you changed Dockerfiles or dependency manifests, rebuild explicitly:

./scripts/dev/up.sh --build

3. Start the host executor in a separate terminal:

./scripts/setup/host-executor-local.sh
./scripts/dev/run-host-executor.sh

4. Open the application:

• frontend: http://localhost:3000
• backend docs: http://localhost:8000/docs
• diagnostics: http://localhost:3000/diagnostics
• runs: http://localhost:3000/runs
• repositories: http://localhost:3000/repos

If no admin account exists yet, the root UI will redirect to /setup for first-run initialization.

5. Stop the control plane:

./scripts/dev/down.sh

Host Requirements

Required tools and auth checks

git --version
gh --version
gh auth status
gh auth setup-git
codex --help
codex login status
claude --version
claude auth status

Minimum expectations:

• git is installed
• gh is installed and already authenticated
• at least one supported runtime CLI is installed and already authenticated
• the host executor runs under the same OS user that owns those CLI sessions

Repository Layout

apps/
  backend/        FastAPI, SQLAlchemy, Alembic
  web/            Next.js, TypeScript, Tailwind, shadcn/ui
  host-executor/  Host-side execution bridge for codex, claude, gh, git, PTY, and tmux
docs/             Architecture and operational documentation
images/           README and product screenshots
infra/            Local compose setup and infrastructure assets
scripts/          Local development and operational scripts

Local Validation

Backend:

cd apps/backend
python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
python -m ruff check app tests
python -m pytest

Frontend:

cd apps/web
npm install
npm run lint
npm run build

Demo Seeding

Demo data is not created during normal startup.

• clean install: no starter team is added automatically unless selected in the /setup UI;
• ./scripts/dev/seed-demo.sh: seeds a demo user and a few demo agents;
• ./scripts/dev/reset-demo-data.sh: resets catalog data and seeds the full demo catalog, including Fullstack Delivery Squad.

Documentation

• Architecture Overview
• Runtime Boundary RFC
• Run Resume and Recovery
• Live-Fire Validation Plan
• Contributing

Open-Source Direction

This repository is being prepared for open development.

That means:

• public-facing documentation should be in English;
• product and architecture intent should live in versioned docs inside the repository;
• current guidance should come from this README and the docs listed above.

License

This project is released under the MIT License.