Contributing to cctop

Thanks for helping improve cctop! It's a single Bun/TypeScript program with no build step and zero runtime dependencies. This guide covers local setup; see AGENTS.md for the architecture, conventions, and invariants.

Prerequisites

cctop runs on Bun; formatting and linting use Biome, and type-checking uses the TypeScript compiler (tsc). On macOS, install them with Homebrew:

brew install bun biome typescript

Bun is the only hard requirement — Biome and TypeScript are also listed as devDependencies, so bun install pulls them in as well.

Getting started

git clone https://github.com/stefanprodan/cctop.git
cd cctop
bun install

Development

Run the TUI with live reload — Bun restarts it whenever you edit cctop.ts or anything under src/:

make dev                 # bun --watch cctop.ts
make dev ARGS="flux"     # pass a filter

Other useful targets:

make start       # run once, without the file watcher
make test        # bun test (the unit suite under test/)
make lint        # Biome format + lint, then tsc --noEmit
make build       # compile a standalone binary into bin/

Always run make lint test before a commit.

Using Claude Code

The guidance for AI agents lives in AGENTS.md. Rather than add a CLAUDE.md, you can have Claude Code load it automatically with a SessionStart hook: on each session it checks for an AGENTS.md at the repo root (and no CLAUDE.md) and tells Claude to read it.

Add this to your Claude Code settings — ~/.claude/settings.json to cover all your repos, or .claude/settings.json for just this one (requires jq):

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "root=$(git rev-parse --show-toplevel 2>/dev/null || pwd); if [ -f \"$root/AGENTS.md\" ] && [ ! -f \"$root/CLAUDE.md\" ]; then jq -n '{hookSpecificOutput:{hookEventName:\"SessionStart\",additionalContext:\"Read AGENTS.md at the repository root in full now, and follow it for the rest of the session.\"}}'; fi 2>/dev/null || true",
            "statusMessage": "Loading AGENTS.md"
          }
        ]
      }
    ]
  }
}

With this in place, every Claude Code session in a repo that has an AGENTS.md picks up its architecture, conventions, and the read-only / zero-dependency rules — no per-repo CLAUDE.md needed.