Fastcoder

CLI tool to register, inspect and report on local development projects.

Features

• Register and remove projects (persisted in SQLite at ~/.fastcoder/fastcoder.db)
• Read each project's tasks folder (default .docs/, configurable via TASKS_FOLDER in .env or the global settings — e.g. .docs/config.json with a checks array of shell commands)
• Run shell commands inside any registered project
• Run periodic check passes and store reports
• Drive coding tasks through stage folders and implement them with Claude Code (do / continue)
• Run a single global do that walks every project round-robin until one has a task to execute
• Track every Claude Code run as an execution (status, tokens, usage-limit headroom)
• Retry failed tasks automatically and quarantine repeat failures in a failures/ stage
• Record exceptions for interrupted runs and an action log of every step
• Full web interface (React + Vite + Express, TypeScript) exposing every feature — manage projects, the task board, executions, exceptions, logs, reports, the scheduled job and settings
• Install/remove a system crontab entry that runs the checks on a schedule

Install (global CLI)

Prerequisites

• Node.js ≥ 22 (Node 22 LTS or Node 24 LTS recommended). Older Node versions are unsupported — Node 18 reached end-of-life in April 2025 and better-sqlite3 no longer ships prebuilt binaries for them.
• A C/C++ toolchain only if no prebuilt binary exists for your Node version/platform (see Troubleshooting below). Prebuilt binaries are shipped for the recommended Node LTS versions, so most users do not need a compiler.

Install

cd /Users/username/projects/fastcoder
npm install
npm install -g .

Now fastcoder is on your PATH.

Troubleshooting install

If npm install (or npm i -g fastcoder) fails while building better-sqlite3 with an error like make: cc: No such file or directory or prebuild-install warn install No prebuilt binaries found, the native SQLite addon is falling back to compiling from source because no prebuilt binary matches your Node/OS combination — and the system has no C compiler. Fixes (pick one):

• Use a Node version with a prebuilt binary (cheapest). Switch to Node 22 LTS or Node 24 LTS:

  nvm install 22 && nvm use 22
  npm i -g fastcoder

• Install the build toolchain so the source compile succeeds:

  • Linux / WSL (Debian/Ubuntu): sudo apt-get update && sudo apt-get install -y build-essential python3
  • macOS: xcode-select --install
  • Windows (PowerShell as admin): npm i -g windows-build-tools (or install "Desktop development with C++" from the Visual Studio Build Tools)

  Then re-run npm i -g fastcoder.

Quick start

fastcoder register --name my-app --path /path/to/repo
fastcoder list
fastcoder check
fastcoder serve            # http://localhost:4787
fastcoder cron:install     # every 15 minutes by default (macOS/Linux/WSL/Windows)
fastcoder run my-app "git status"

Run without arguments for an interactive menu:

fastcoder

Task workflow

Fastcoder drives coding tasks through a set of stage folders inside each project's tasks folder (default .docs/tasks/; change the name via the TASKS_FOLDER variable in .env or in the global settings). Create the structure once:

fastcoder init my-app

This creates tasks/{backlog,ai-backlog,todo,doing,done,totest,testing,tovalidate,validating,failures,periodic}. Drop a Markdown task file (one feature per file) into tasks/todo/ describing what you want done.

do — implement the next task

fastcoder do my-app      # one project
fastcoder do             # global: every project, round-robin

do runs a full workflow for the project:

1. Runs a check pass to inspect task status.
2. If the project has a task that failed on a previous do, that task is retried first (see below). Otherwise it moves the first file in tasks/todo/ into tasks/doing/.
3. Runs Claude Code against the task file in tasks/doing/ to implement it.
4. On success, moves the file to tasks/totest/.
5. On failure, the file stays in tasks/doing/ and an exception is recorded — pending when the run can be resumed (e.g. a usage limit was hit) or ignored when it cannot.

Failure retries. The next time do runs for a project with a failed task, it resumes that task (a continue-style run) to analyse and fix the failure. If the retry succeeds the task moves to tasks/totest/; if it fails again the task is moved to tasks/failures/ and the exception is marked failed-solving.

Global do. With no project, fastcoder do walks every registered project, starting from the one after the project executed last time. It stops at the first project that has a task to run, executes it and exits — so a scheduled fastcoder do makes steady round-robin progress across all projects.

executions — track Claude Code runs

Every Claude Code run started by do is recorded as an execution. An execution is in-progress while Claude runs and becomes success or fail when it ends, capturing token usage and remaining usage-limit headroom when available:

fastcoder executions                          # recent executions
fastcoder executions -p my-app -s in-progress # what is still running
fastcoder executions 42                       # full detail of one execution

Execution statuses: in-progress, success, fail.

continue — resume interrupted runs

fastcoder continue my-app      # one project
fastcoder continue             # every project

continue re-runs Claude Code for each pending exception. A resumed run that completes flips the exception to solved and moves the task to tasks/totest/; a run that fails again flips it to failed-solving.

exceptions and logs — inspect what happened

Every do / continue step is recorded in an action log, and failed runs are recorded as exceptions. Both can be listed and filtered:

fastcoder exceptions                          # all exceptions
fastcoder exceptions -p my-app -s pending     # filter by project and status
fastcoder logs -p my-app -a do                # logs for the `do` action
fastcoder logs --level error                  # only error-level logs

Exception statuses: pending, solved, ignored, failed-solving. Log levels: info, warn, error.

Web interface

fastcoder serve starts an Express server that exposes every application feature as a JSON API under /api and serves a React single-page app for the UI. The web app lives in web-ui/ (React 18 + Vite + TypeScript, PrimeReact components, Tailwind CSS, React Router, TanStack Query for state, and react-hook-form + zod for validation).

npm run build:web          # install web-ui deps and build the SPA into web-ui/dist
fastcoder serve           # serves the built SPA + API at http://localhost:4787

The interface has a sidebar with menu navigation, a header and a footer, and covers the whole feature surface: a Dashboard overview, full project CRUD, a per-project workspace with a kanban-style task board (create / edit / move / delete task files) and the do / check / continue / run-command actions, plus pages for executions, exceptions, action logs, reports, the scheduled job and global settings.

For UI development, run the API and the Vite dev server side by side — Vite proxies /api to the running fastcoder serve:

fastcoder serve                 # API on :4787
npm --prefix web-ui run dev      # Vite dev server on :4788, proxying /api

Using make

A Makefile (with one sub-file per command group under ./make/) wraps the CLI so you can drive everything with make:

make help                                     # list every target
make install                                  # npm install + tsc build
make build                                    # tsc only
make watch                                    # tsc --watch
make dev                                      # run CLI from TS via ts-node
make install-global                           # npm install -g . (auto-compiles)

make register NAME=my-app DIR=/path/to/repo
make list
make remove  TARGET=my-app

make check                                    # all projects
make check   TARGET=my-app                    # one project
make reports LIMIT=10

make serve                                    # default port 4787
make serve   PORT=8080

make cron-install                             # */15 * * * * by default
make cron-install SCHEDULE="*/30 * * * *"
make cron-uninstall
make cron-status

make run TARGET=my-app CMD="git status"
make menu                                     # interactive

Sub-makefiles:

make/install.mk    install, install-global, uninstall-global, clean, menu
make/projects.mk   register, list, remove
make/check.mk      check, reports
make/serve.mk      serve
make/cron.mk       cron-install, cron-uninstall, cron-status
make/run.mk        run

<tasks-folder>/config.json example

Place this file inside a registered project (the folder defaults to .docs/, override with TASKS_FOLDER or the global settings):

{
  "checks": [
    "git status --porcelain",
    "npm outdated --json"
  ]
}

Each command is executed inside the project folder during fastcoder check, and its stdout/stderr/exit code are stored in the report.

Layout (TypeScript)

src/
  cli.ts                          # entry: runs runMain() when invoked directly
  program.ts                      # buildProgram() + runCommand() (commander wiring)
  config.ts                       # paths/constants
  cli/                            # one file per CLI command (commander actions)
  domain/                         # Project, Report, TaskException, ActionLog, Execution (typed)
  application/                    # use-case services
  actions/                        # single-responsibility actions (run-claude-task)
  infrastructure/                 # better-sqlite3, fs, shell, system-cron, express
tsconfig.json                     # target ES2020, module commonjs, strict, outDir dist
dist/                             # compiled output (created by `make build`)
bin/fastcoder.js                 # thin shim: require('../dist/cli').runMain()

npm install runs the prepare script which compiles to dist/. Both fastcoder (compiled) and make dev (via ts-node src/cli.ts) work.