Overview (Cloud Edition)

AI coding agents are increasingly writing the world's code and human engineers now spend the majority of their time planning, reviewing, and orchestrating tasks. Vibe Kanban streamlines this process, enabling you to:

• Easily switch between different coding agents
• Orchestrate the execution of multiple coding agents in parallel or in sequence
• Quickly review work across teams and projects
• Track the status of tasks that your coding agents are working on
• Centralise configuration of coding agent MCP configs

Quick Start

Run without installing:

PORT=6767 BACKEND_PORT=6767 npx -y @nogataka/coding-agent-mgr@latest

The bundled server starts on port 6767 (this example overrides the default 5555) and automatically opens http://localhost:6767 once it is reachable. If your shell does not support PORT=... prefix notation, export the variables before running the command.

Global install

npm install -g @nogataka/coding-agent-mgr
coding-agent-mgr

From source

git clone https://github.com/nogataka/coding-agent-mgr.git
cd coding-agent-mgr
npm run install:all
npm run build:npx
CODING_AGENT_MODE=local BACKEND_PORT=5555 NODE_ENV=production node npx-cli/bin/cli.js

Make sure you have authenticated with your favourite coding agent. A full list of supported coding agents is available in the docs.

Launch Modes (CODING_AGENT_MODE)

CODING_AGENT_MODE (note the trailing E) controls how the bundled runtime boots. If you leave it unset, the CLI defaults to local mode.

Local Mode (local, default)

This mode is ideal for interactive usage on a development machine. Once the backend passes the health check the CLI automatically opens your browser.

• Prerequisites: Node.js ≥ 18, npm ≥ 9 (or pnpm ≥ 8). Sign in to any coding agents you plan to orchestrate.
• Running from the published package:
  1. Execute npx -y @nogataka/coding-agent-mgr@latest. The command downloads the prebuilt runtime and starts the bundled backend.
  2. Override BACKEND_PORT=5555 (default) or HOST=127.0.0.1 before the command if you need different ports or bindings.
  3. Wait for the CLI to print 🚀 Launching coding-agent-mgr…; if your browser does not open automatically, navigate to http://localhost:${BACKEND_PORT} manually.
• Running from this repository (useful during development):
  1. npm run install:all
  2. npm run build:npx to produce the distributable runtime under npx-cli/dist/
  3. CODING_AGENT_MODE=local BACKEND_PORT=5555 NODE_ENV=production node npx-cli/bin/cli.js
  4. Verify the backend with curl http://localhost:5555/api/health
• Data directories: In production mode the runtime stores state under:
  • macOS: ~/Library/Application Support/coding-agent-mgr
  • Linux: ~/.local/share/coding-agent-mgr (or $XDG_DATA_HOME/coding-agent-mgr when defined)
  • Windows: %APPDATA%\coding-agent-mgr Set CODING_AGENT_DATA_DIR if you prefer a different location (handy for disposable sandboxes).
• Workspace root: Override CODING_AGENT_USER_CWD to point the agents at another workspace. By default it resolves to the directory where you invoked the CLI.

Server Mode (server)

This headless mode suits remote or always-on environments. The CLI skips auto-opening a browser, keeps the backend ready for reverse proxies, and honors the same environment variables as local mode.

• When to use it: Host behind nginx/Traefik, run under Docker or systemd, or operate in environments where launching a browser is not possible.
• Baseline setup:

  1. Build the runtime (npm run build:npx) on a machine with the repository, or obtain the published package.

  2. Copy npx-cli/dist/ to the target host if you deploy manually.

  3. Set the required environment variables before launching:

     export NODE_ENV=production
     export CODING_AGENT_MODE=server
     export HOST=0.0.0.0            # listen on all interfaces
     export BACKEND_PORT=3001       # adjust to match your ingress
     export CODING_AGENT_DATA_DIR=/var/lib/coding-agent-mgr
     export CODING_AGENT_USER_CWD=/srv/coding-agent-mgr

  4. Start the runtime with npx -y @nogataka/coding-agent-mgr@latest (published package) or node npx-cli/bin/cli.js (local build).

  5. Confirm curl http://127.0.0.1:${BACKEND_PORT}/api/health returns HTTP 200 before connecting your reverse proxy.

• Docker / Compose: The bundled docker-compose.yml demonstrates a production setup with CODING_AGENT_MODE=server, nginx-proxy, and Let’s Encrypt. Adjust ports, volumes, and secrets, then run docker compose up -d.
• Persistent storage: Always provision the directory referenced by CODING_AGENT_DATA_DIR; it stores the SQLite database, logs, cached repositories, and agent settings. Ensure the runtime user has read/write permissions.
• Frontend assets: In server mode the backend serves static assets from CODING_AGENT_FRONTEND_DIR. Point this variable elsewhere if you host the frontend separately.

Both modes expose the same health-check endpoint (/api/health) and honor SIGINT/SIGTERM for graceful shutdown. Use these signals when integrating with process managers such as systemd, PM2, or Docker.

Support

Please open an issue on this repo if you find any bugs or have any feature requests.

Contributing

We would prefer that ideas and changes are raised with the core team via GitHub issues, where we can discuss implementation details and alignment with the existing roadmap. Please do not open PRs without first discussing your proposal with the team.

Development

Prerequisites

• Node.js (>=18)
• npm (>=9) or pnpm (>=8)

Project Structure

coding-agent-mgr/
├── backend/         # Node.js/TypeScript backend
│   ├── server/      # Express API server
│   ├── db/          # Database layer (SQLite)
│   ├── services/    # Business logic
│   ├── executors/   # AI engine integration
│   ├── deployment/  # Deployment management
│   └── utils/       # Shared utilities
├── frontend/        # React UI
└── shared/          # Shared TypeScript types

Installation

Install all dependencies:

npm run install:all

Running the Development Server

Start both frontend and backend in development mode:

npm run dev

This will start:

• Frontend: http://localhost:3000
• Backend: http://localhost:3001

Individual servers:

npm run frontend:dev  # Frontend only
npm run backend:dev   # Backend only

Building

Build both frontend and backend:

npm run build

Testing & Quality

# Type checking
npm run check          # Check both frontend and backend
npm run backend:check  # Backend only
npm run frontend:check # Frontend only

# Linting & Formatting (backend)
cd backend
npm run lint           # ESLint
npm run format         # Prettier format
npm run format:check   # Prettier check
npm run typecheck      # TypeScript check

Database Management

cd backend
npm run db:migrate     # Run migrations
npm run db:reset       # Reset database

Environment Variables

The following environment variables can be configured. Frontend build-time values are read by Vite; copy frontend/.env.example to frontend/.env.local (or another .env file) as needed and rebuild the frontend after any change.

| Variable | Type | Default | Description | |----------|------|---------|-------------| | GITHUB_CLIENT_ID | Build-time | xxxx | GitHub OAuth app client ID for authentication | | VITE_PROJECT_MODE | Build-time | github | Frontend project creation mode. Set to local to restore local repository workflows; other values fall back to GitHub mode. | | POSTHOG_API_KEY | Build-time | Empty | PostHog analytics API key (disables analytics if empty) | | POSTHOG_API_ENDPOINT | Build-time | Empty | PostHog analytics endpoint (disables analytics if empty) | | PORT | Runtime | 3001 | Backend server port | | BACKEND_PORT | Runtime | 3001 | Alternative backend server port | | FRONTEND_PORT | Runtime | 3000 | Frontend development server port | | HOST | Runtime | 127.0.0.1 | Backend server host | | DISABLE_WORKTREE_ORPHAN_CLEANUP | Runtime | Not set | Disable git worktree cleanup (for debugging) |

Port Configuration

Development ports are configured in .dev-ports.json:

{
  "frontend": 3000,
  "backend": 3001
}

API Compatibility

This TypeScript/Node.js version maintains 95%+ API compatibility with the original Rust implementation. See API_COMPARISON_FINAL.md for detailed compatibility information.

Custom GitHub OAuth App (Optional)

By default, Vibe Kanban uses Bloop AI's GitHub OAuth app for authentication. To use your own GitHub app for self-hosting or custom branding:

1. Create a GitHub OAuth App at GitHub Developer Settings
2. Enable "Device Flow" in the app settings
3. Set scopes to include user:email,repo
4. Set the environment variable:

   GITHUB_CLIENT_ID=your_client_id_here npm run build

Migration from Rust Version

This TypeScript/Node.js implementation is designed to be a drop-in replacement for the Rust version. All data formats, API endpoints, and frontend interactions remain compatible. Simply stop the Rust server and start the Node.js server to switch implementations.

Performance Considerations

While the TypeScript/Node.js version may have slightly different performance characteristics compared to the Rust version, it offers:

• Easier deployment and maintenance
• Broader ecosystem compatibility
• Simplified development workflow
• Full feature parity

License

See the LICENSE file for details.

This project is a React port of BloopAI/vibe-kanban, originally licensed under Apache License 2.0.
Additional modifications © 2025 nogataka.