npm package: @nogataka/coding-agent-mgr
Description: 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:
Latest version: 0.1.6

## 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:

```bash
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

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

### From source

```bash
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](https://vibekanban.com/).

## 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:

     ```bash
     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](https://nodejs.org/) (>=18)
- [npm](https://www.npmjs.com/) (>=9) or [pnpm](https://pnpm.io/) (>=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:
```bash
npm run install:all
```

### Running the Development Server

Start both frontend and backend in development mode:
```bash
npm run dev
```

This will start:
- Frontend: http://localhost:3000
- Backend: http://localhost:3001

Individual servers:
```bash
npm run frontend:dev  # Frontend only
npm run backend:dev   # Backend only
```

### Building

Build both frontend and backend:
```bash
npm run build
```

### Testing & Quality

```bash
# 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

```bash
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`:
```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](https://github.com/settings/developers)
2. Enable "Device Flow" in the app settings
3. Set scopes to include `user:email,repo`
4. Set the environment variable:
   ```bash
   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](https://github.com/BloopAI/vibe-kanban),
originally licensed under Apache License 2.0.  
Additional modifications © 2025 nogataka.