# AutoCode CLI

> Local SQLite-based issue tracking system with automated AI code validation

A Claude Code wrapper that orchestrates AI-generated code through a customizable validation pipeline. Includes web dashboard, real-time Kanban board, and REST API. All data is stored locally in a single SQLite database file.

[![npm version](https://img.shields.io/npm/v/@autocode-cli/autocode.svg)](https://www.npmjs.com/package/@autocode-cli/autocode)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![License](https://img.shields.io/badge/license-SEE%20LICENSE-blue)](LICENSE)

**[Live Demo](https://evkoh.gitlab.io/autocode/)** | **[Interactive Kanban Demo](https://evkoh.gitlab.io/autocode/demo.html)**

## Screenshots

### Landing Page
![AutoCode Landing Page](https://gitlab.com/evkoh/autocode/-/raw/main/public/screenshots/landing.png)

### Dashboard
![AutoCode Dashboard](https://gitlab.com/evkoh/autocode/-/raw/main/public/screenshots/dashboard.png)

### Issue Modal
![AutoCode Issue Modal](https://gitlab.com/evkoh/autocode/-/raw/main/public/screenshots/issue-modal.png)

### Architecture
![AutoCode Architecture](https://gitlab.com/evkoh/autocode/-/raw/main/public/screenshots/architecture.png)

## What is AutoCode?

AutoCode is a **Claude Code wrapper** that automatically validates AI-generated code through a customizable pipeline. It combines:

- **Issue Tracking**: Local SQLite database with Prisma ORM for fast, reliable data management
- **AI Orchestration**: Wraps Claude Code (`claude -p`) to process issues through validation stages
- **Automated Validation**: Reviews for best practices, duplication, consistency, and security
- **Automated Testing**: Integration with Playwright and Cypress for E2E testing

**How it works:**
1. Create an issue describing what you want to build
2. Claude Code implements the code
3. AutoCode automatically validates through the pipeline (reviews, tests, security)
4. Issue advances to Done when all validations pass

All data is stored in a local SQLite database (`autocode/autocode.db`) - zero configuration, portable, single file.

## Key Features

| Feature | Description |
|---------|-------------|
| **Claude Code Wrapper** | Orchestrates Claude AI to process issues through the pipeline |
| **Customizable Pipeline** | Define your own validation columns (reviews, tests, deploys) |
| **Real-time Dashboard** | Web Kanban board with WebSocket updates |
| **AI Pipeline Generator** | Auto-detect your stack and propose relevant columns |
| **Local SQLite Database** | Single file database with Prisma ORM - portable and fast |
| **REST API** | Full API for integrations and automations |
| **Multi-language** | Supports English and French |
| **Issue Hierarchy** | Parent-child relationships between issues |
| **Speech-to-Text** | Voice dictation for issue creation with autocomplete |

## Speech-to-Text Feature

The dashboard includes voice dictation for quick issue creation:

### How it works

1. **Click the microphone button** next to the title field on the New Issue page
2. **Speak your issue title** - the text is transcribed in real-time
3. **Autocomplete triggers** - after you stop speaking, a 3-second countdown starts
4. **AI fills the form** - Claude suggests description, priority, labels, and acceptance criteria

### Supported browsers

| Browser | Support |
|---------|---------|
| Chrome | Full support |
| Edge | Full support |
| Safari | Full support (webkit) |
| Firefox | Not supported (button disabled) |

### Language support

- **French** (fr-FR) - Select "FR" in the language switcher
- **English** (en-US) - Select "EN" in the language switcher

### Fallback behavior

On unsupported browsers, the microphone button is automatically disabled with a tooltip explaining the limitation. A notification appears if the user attempts to click it.

## Installation

```bash
npm install -g @autocode-cli/autocode
```

## Quick Start

```bash
# Initialize project structure
autocode init

# Create a new issue (with all options)
autocode new "Implement user authentication" "OAuth2 login with Google and GitHub" --priority P1 --labels "feature,auth" --acceptance "Login button visible,OAuth flow works,Token stored" --semver minor --column backlog

# List all issues
autocode list

# Show issue details
autocode show AC-000001

# Move issue to next column
autocode next AC-000001

# Start web dashboard
autocode serve
```

## CLI Reference

### Main Commands

| Command | Description |
|---------|-------------|
| `serve` | Start web dashboard (default command) |
| `init` | Initialize autocode project structure |
| `new <title> [description]` | Create a new issue |
| `list` | List all issues |
| `show <issue-key>` | Show issue details |
| `history <issue-key>` | Show full issue history with prompts and terminal output |
| `move <issue-key> <column-slug>` | Move issue to specific column |
| `next <issue-key>` | Advance issue to next column |
| `comment <issue-key> <text>` | Add comment to issue |
| `parent <issue-key> [parent-key]` | Manage parent relationships |
| `health` | Check workflow health (stuck issues) |
| `stats` | Show Claude usage statistics |
| `catalog` | List available columns in catalog |
| `pipeline <action>` | Manage pipelines |
| `help` | Show help message |

### Pipeline Commands

| Command | Description |
|---------|-------------|
| `pipeline list` | List all pipelines |
| `pipeline show <name>` | Show pipeline with columns |
| `pipeline create <name>` | Create new pipeline |
| `pipeline delete <name>` | Delete pipeline version |
| `pipeline activate <name>` | Activate pipeline version |
| `pipeline versions <name>` | List all versions |
| `pipeline draft <name>` | Create draft from latest |
| `pipeline finalize <name>` | Finalize draft |
| `pipeline add-column <pipeline> <slug>` | Add column to pipeline |
| `pipeline remove-column <pipeline> <slug>` | Remove column from pipeline |
| `pipeline move-column <pipeline> <slug>` | Move column between segments |

### Catalog Commands

| Command | Description |
|---------|-------------|
| `catalog` | List available columns |
| `catalog add <slug>` | Add new column to catalog |

## CLI Options

### serve
| Option | Description |
|--------|-------------|
| `-p, --port <port>` | Server port (default: 3000) |
| `-e, --expose` | Expose via Cloudflare tunnel |

### new
| Option | Description |
|--------|-------------|
| `-p, --priority <P0-P3>` | Set priority (default: P2) |
| `-l, --labels <labels>` | Comma-separated labels |
| `-a, --acceptance <criteria>` | Comma-separated acceptance criteria |
| `-s, --semver <type>` | Semver type (major\|minor\|patch) |
| `-c, --column <slug>` | Target column (default: backlog) |
| `--parent <key>` | Parent issue key |
| `--autocomplete` | AI-generate fields via API |
| `--lang <en\|fr>` | Language for autocomplete |

### list
| Option | Description |
|--------|-------------|
| `-c, --column <slug>` | Filter by column |
| `-p, --priority <P0-P3>` | Filter by priority |
| `-l, --label <label>` | Filter by label |
| `--parent <key>` | Filter by parent |
| `--tree` | Display as tree |
| `--json` | Output as JSON |

### show
| Option | Description |
|--------|-------------|
| `--json` | Output as JSON |

### history
| Option | Description |
|--------|-------------|
| `--json` | Output as JSON (includes all data) |
| `--full` | Show complete prompt and terminal content |
| `--limit <N>` | Show only last N entries |

### move
| Option | Description |
|--------|-------------|
| `-f, --force` | Force move (skip validation) |

### health
| Option | Description |
|--------|-------------|
| `--json` | Output as JSON |
| `-v, --verbose` | Show detailed information |

### stats
| Option | Description |
|--------|-------------|
| `--json` | Output as JSON |
| `--session` | Show only session stats |
| `--totals` | Show only total stats |

### pipeline
| Option | Description |
|--------|-------------|
| `--version <N>` | Specific version |
| `--json` | Output as JSON |
| `--description "..."` | Pipeline description |
| `--segment <segment>` | Segment (definition\|action\|finish) |
| `--position <N>` | Position in segment |
| `--name "Display Name"` | Column display name |
| `--activate` | Activate after finalizing |

### catalog add
| Option | Description |
|--------|-------------|
| `--segment <segment>` | Segment (definition\|action\|finish) |
| `--name "..."` | Display name |
| `--description "..."` | Column description |

## CLI Examples

```bash
# Start server
autocode                                    # Default port 3000
autocode serve -p 8080                      # Custom port
autocode serve --expose                     # With Cloudflare tunnel

# Issues
autocode show AC-000001                     # Show issue details
autocode show AC-000001 --json              # JSON output
autocode history AC-000001                  # Show full history
autocode history AC-000001 --full           # With complete logs
autocode list                               # List all issues
autocode list -c in-progress                # Filter by column
autocode list --tree                        # Show hierarchy
autocode list --json                        # JSON output
autocode new "Fix bug" -p P1 -l bug         # Create issue
autocode new "Feature" "Desc" -a "Works"    # With acceptance criteria
autocode next AC-000001                     # Advance to next column
autocode move AC-000001 done                # Move to specific column
autocode move AC-000001 backlog --force     # Force move
autocode comment AC-000001 "Done"           # Add comment
autocode parent AC-000001                   # Show parent/children
autocode parent AC-000001 AC-000002         # Set parent
autocode parent AC-000001 none              # Remove parent

# Workflow
autocode health                             # Check for stuck issues
autocode health --verbose                   # Detailed info
autocode stats                              # Show usage stats
autocode stats --session                    # Session only

# Pipelines
autocode pipeline list                      # List all pipelines
autocode pipeline show default              # Show pipeline details
autocode pipeline show default --json       # JSON output
autocode pipeline create my-pipeline        # Create new pipeline
autocode pipeline draft default             # Create draft
autocode pipeline add-column default review --segment action
autocode pipeline remove-column default review
autocode pipeline move-column default review --segment finish
autocode pipeline finalize default          # Lock draft
autocode pipeline finalize default --activate  # Lock and activate
autocode pipeline activate default          # Activate latest
autocode pipeline activate default --version 2  # Activate specific
autocode pipeline versions default          # List versions
autocode pipeline delete default            # Delete draft

# Catalog
autocode catalog                            # List columns
autocode catalog --json                     # JSON output
autocode catalog add review-perf --segment action --name "Performance Review"

```

## Versioned Pipelines

AutoCode uses **versioned and immutable pipelines**. Pipelines are organized into three segments:

| Segment | Purpose |
|---------|---------|
| **definition** | Define what needs to be done (backlog, ready) |
| **action** | Execute the work (in-progress, reviews, tests) |
| **finish** | Validate and complete (done) |

### Pipeline Commands

```bash
# List all pipelines
autocode pipeline list

# Show pipeline details
autocode pipeline show default

# Create a draft from latest version
autocode pipeline draft default

# Add a column to the draft
autocode pipeline add-column default review-security --segment action

# Finalize and activate
autocode pipeline finalize default --activate
```

### Column Catalog

Available columns can be listed with `autocode catalog`. Add custom columns to the catalog for reuse across pipelines.

## Project Structure

```
autocode/
├── autocode.db             # SQLite database (issues, history, pipelines, prompts)
└── attachments/            # Uploaded files (images, documents)
    └── AC-000001/          # Attachments organized by issue key

templates/
├── catalog.yaml            # Column catalog definition
├── analysis-prompt.en.md   # Analysis prompt (English)
├── analysis-prompt.fr.md   # Analysis prompt (French)
└── prompts/                # Default prompt templates (Git-versioned)
    ├── backlog.en.md       # English template
    ├── backlog.fr.md       # French template
    └── ...                 # One per column per language
```

**Note:** Column prompts are stored in the SQLite database (`column_prompts` table). The `templates/prompts/` directory contains default templates used as fallback when no custom prompt is defined in the database.

### Database Schema

The SQLite database (`autocode.db`) contains:

| Table | Description |
|-------|-------------|
| `issues` | All issues with title, description, priority, column, parent |
| `acceptance_criteria` | Acceptance criteria for each issue |
| `issue_history` | Full audit trail of all moves and edits |
| `comments` | Issue comments with author and timestamp |
| `attachments` | File attachment metadata (files stored on disk) |
| `execution_logs` | Claude CLI execution prompts and terminal output |
| `pipelines` | Versioned pipeline definitions (immutable once locked) |
| `columns` | Column configuration within pipelines |
| `column_prompts` | Custom action prompts per column per language |
| `sequences` | Auto-increment counters (AC-XXXXXX keys) |

## Issue Format

Issues are stored in the SQLite database. The API returns JSON:

```json
{
  "key": "AC-000001",
  "title": "Implement feature X",
  "description": "Feature description in markdown...",
  "column_slug": "02_in-progress",
  "priority": "P1",
  "semver": "minor",
  "labels": ["feature", "backend"],
  "parent_key": null,
  "acceptance_criteria": [
    { "id": 1, "criterion": "Login button visible", "position": 0 },
    { "id": 2, "criterion": "OAuth flow works", "position": 1 }
  ],
  "comments": [
    {
      "id": "1704272400000",
      "content": "Implementation started",
      "author": "claude",
      "created_at": "2024-01-15T10:00:00Z"
    }
  ],
  "history": [
    {
      "at": "2024-01-15T10:00:00Z",
      "action": "created",
      "from_column": null,
      "to_column": "00_backlog"
    }
  ],
  "created_at": "2024-01-15T10:00:00Z",
  "updated_at": "2024-01-15T12:00:00Z"
}
```

## API Reference

When running `autocode serve` (default port 3000):

### Issues

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/issues` | List all issues |
| POST | `/api/issues` | Create new issue |
| GET | `/api/issues/:key` | Get issue details |
| PATCH | `/api/issues/:key` | Update issue |
| DELETE | `/api/issues/:key/archive` | Archive issue |
| POST | `/api/issues/:key/move` | Move to column |
| POST | `/api/issues/:key/next` | Advance to next column |
| GET | `/api/issues/:key/comments` | List comments |
| POST | `/api/issues/:key/comments` | Add comment |
| GET | `/api/issues/:key/history` | Get issue history |
| GET | `/api/issues/:key/full-history` | Get history with prompts and terminal logs |
| GET | `/api/issues/:key/full-terminal` | Get all terminal logs |
| GET | `/api/issues/:key/log` | Get latest execution log |
| GET | `/api/issues/:key/:column/log` | Get column-specific log |
| GET | `/api/issues/:key/history/:sessionId/log` | Get session terminal log |
| GET | `/api/issues/:key/history/:sessionId/prompt` | Get session prompt |
| GET | `/api/issues/:key/ancestors` | Get parent chain |
| GET | `/api/issues/:key/children` | Get child issues |
| GET | `/api/issues/:key/attachments` | List attachments |
| POST | `/api/issues/:key/attachments` | Upload attachment |
| GET | `/api/issues/:key/attachments/:id` | Download attachment |
| DELETE | `/api/issues/:key/attachments/:id` | Delete attachment |
| GET | `/api/issues/actionable` | Get actionable issues |
| GET | `/api/issues/graph` | Get issue dependency graph |
| POST | `/api/issues/autocomplete` | AI autocomplete for issue fields |

### Pipelines

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/pipelines` | List all pipelines |
| POST | `/api/pipelines` | Create new pipeline |
| GET | `/api/pipelines/:name` | Get pipeline details |
| PUT | `/api/pipelines/:name` | Update pipeline |
| DELETE | `/api/pipelines/:name` | Delete pipeline |
| PUT | `/api/pipelines/:name/activate` | Activate latest version |
| GET | `/api/pipelines/:name/versions` | List all versions |
| POST | `/api/pipelines/:name/versions` | Create new draft |
| GET | `/api/pipelines/:name/versions/:version` | Get specific version |
| PUT | `/api/pipelines/:name/versions/:version` | Update draft |
| DELETE | `/api/pipelines/:name/versions/:version` | Delete version |
| POST | `/api/pipelines/:name/versions/:version/finalize` | Finalize draft |
| PUT | `/api/pipelines/:name/versions/:version/activate` | Activate version |

### Columns

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/columns` | List all columns |
| GET | `/api/columns/:slug/actions` | Get column ACTION content |
| GET | `/api/columns/:slug/prompt` | Get column prompt |

### Catalog

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/catalog` | List column catalog |
| POST | `/api/catalog` | Add column to catalog |
| POST | `/api/catalog/autocreate` | Auto-generate columns from project |
| POST | `/api/catalog/autocreate/apply` | Apply generated columns |

### Monitoring & Status

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/health` | Health check |
| GET | `/api/status` | Server status |
| GET | `/api/stats` | Claude usage statistics |
| GET | `/api/workflow/health` | Workflow health (stuck issues) |
| GET | `/api/ws/status` | WebSocket status |

### Changelog

| Method | Endpoint | Description |
|--------|----------|-------------|
| GET | `/api/changelog` | Get changelog |
| POST | `/api/changelog/summary` | Generate changelog summary |

## API Examples

```bash
# List all issues
curl http://localhost:3000/api/issues

# Create an issue
curl -X POST http://localhost:3000/api/issues \
  -H "Content-Type: application/json" \
  -d '{"title": "New feature", "priority": "P1", "labels": ["feature"]}'

# Update an issue
curl -X PATCH http://localhost:3000/api/issues/AC-000001 \
  -H "Content-Type: application/json" \
  -d '{"title": "Updated title", "priority": "P0"}'

# Move an issue
curl -X POST http://localhost:3000/api/issues/AC-000001/move \
  -H "Content-Type: application/json" \
  -d '{"column": "in-progress"}'

# Advance to next column
curl -X POST http://localhost:3000/api/issues/AC-000001/next

# Add a comment
curl -X POST http://localhost:3000/api/issues/AC-000001/comments \
  -H "Content-Type: application/json" \
  -d '{"content": "Implementation complete", "author": "claude"}'

# Get full history with logs
curl http://localhost:3000/api/issues/AC-000001/full-history

# List pipelines
curl http://localhost:3000/api/pipelines

# Create a draft
curl -X POST http://localhost:3000/api/pipelines/default/versions

# Add column to draft
curl -X PUT http://localhost:3000/api/pipelines/default/versions/2 \
  -H "Content-Type: application/json" \
  -d '{"action": [{"slug": "review", "name": "Code Review"}]}'

# Finalize and activate
curl -X POST http://localhost:3000/api/pipelines/default/versions/2/finalize
curl -X PUT http://localhost:3000/api/pipelines/default/versions/2/activate

# Auto-generate columns from project
curl -X POST http://localhost:3000/api/catalog/autocreate \
  -H "Content-Type: application/json" \
  -d '{"lang": "en"}'

# Get workflow health
curl http://localhost:3000/api/workflow/health

# Get usage stats
curl http://localhost:3000/api/stats
```

## Environment Variables

| Variable | Description | Default |
|----------|-------------|---------|
| `AUTOCODE_API_URL` | API base URL (required for CLI commands) | - |
| `PORT` | Server port | `3000` |
| `DATABASE_URL` | Prisma database URL | `file:./autocode/autocode.db` |

## License

See [LICENSE](LICENSE) file for details.
