claude-base

What is this?

claude-base is a minimal repository skeleton that wires up a Claude AI agent to automatically work through GitHub issues on your project. You open an issue, the loop picks it up, Claude writes the code, commits it to a branch, and you review and merge. No manual invocation needed.

It is also a template repository. Fork it, drop in your project code, and you get the autonomous loop for free. Claude reads the design goals in CLAUDE.md to stay aligned with your goals, and stores working context in claude/context/ so nothing is forgotten between runs.

The loop is self-improving: if a git pull updates the runner scripts themselves before Claude is invoked, the runner restarts so every session uses the latest code.

How it works

clanker-run

A Bash script that runs under a file lock (no concurrent instances). Before invoking Claude it checksums clanker-run, clanker-prep, and CLAUDE.md. If any of those changed after git maintenance, the script re-execs itself so Claude always sees the freshest runner.

clanker-prep

A Python script that runs every time before Claude is invoked. It fetches from GitHub, fast-forwards main, rebases open branches, prunes merged ones, downloads open issues and CI pipeline results, and writes everything to claude/context/ as YAML. Prints INVOKE_CLAUDE or NOTHING_TO_DO.

Claude's workflow

Governed by CLAUDE.md. In order: read git context, check pipeline results, check open issues, check design files. For each open issue authored by the authorised user, prepare a solution on a dedicated branch. Commit context after every task. Never push — that's for the human guardian.

Housekeeping

A separate daily run via clanker-housekeeping (03:00 local) performs health checks only: which issues have a branch pending review, which have no branch yet, whether any branch is behind main, and whether claude/questions.md has open items. Results go to clanker-housekeeping.json for the dashboard.

Context

Everything Claude learns lives in claude/context/ and is committed to git. Design goals live in claude/design/. Questions for the human go to claude/questions.md. While a session is running, clanker-current.json holds live token/cost counters for the dashboard; it is deleted on exit.

Setup

1. Fork / use this template Click "Use this template" on GitHub to create your own repo from claude-base. Clone it locally.
2. Install Claude Code CLI Follow the Claude Code docs to install the CLI at ~/.local/bin/claude on your server. Authenticate with your Anthropic API key.
3. Install dependencies

   pip install pyyaml

4. Configure the authorized user and GitHub token Edit clanker-prep and set AUTHORIZED_USER to your GitHub username. Only issues from this user will be acted on. Then store a GitHub personal access token so clanker-prep can read issues and pipeline results without hitting the anonymous rate limit:

   git config github.token <your-token>

5. Configure CLAUDE.md Edit CLAUDE.md with your project's goals, stack conventions, and any rules for Claude. This is the primary steering document.
6. Configure git remotes Run setup-remotes to wire up the three remotes used by the workflow. See Remote setup below.
7. Install the timers

   ./clanker-setup

   On systemd systems this creates two user units: a worker that fires every 4 minutes when idle, and a daily housekeeping run at 03:00. On plain cron it installs equivalent */10 and 0 3 * * * entries. The worker is lock-protected and idempotent — safe to run frequently.
8. Open an issue Create a GitHub issue describing what you want built. The next cron tick will pick it up, Claude will create a branch, and you review the diff before merging.

Remote setup

A project using claude-base has three git remotes. Run ./setup-remotes --user <github-user> to configure them:

Workflow

clanker-prep fetches claude-base/main on every run and merges any new commits into your local main if they apply cleanly. If the merge fails (conflict with your changes), it is reported in context so Claude can resolve it.

You stay in sync with upstream improvements without manual intervention. If you customised something that conflicts with a template update, you will see a template_merge_failed entry in claude/context/git_status.yaml.

setup-remotes script

# basic usage — project name defaults to current directory
./setup-remotes --user myusername

# override project name or clanker host
./setup-remotes --user myusername --project myproject --clanker-host myserver

# preview without changing anything
./setup-remotes --user myusername --dry-run

Design principles

Human stays in control

Claude never pushes to GitHub. It prepares branches for human review. Only issues from the configured authorized user are acted on. Destructive or dynamic operations require explicit instructions.

Everything is auditable

All context is in claude/context/ and committed to git. The loop logs everything to clanker.log. Design goals are versioned in CLAUDE.md.

Self-improving

The loop restarts itself if the runner scripts change mid-run. Claude is expected to look for improvements to its own setup and propose them as branches.

Lightweight stack

Python and Bash for tooling. Static data as CBOR. Configuration as YAML. No heavy frameworks. The base is intentionally minimal so it is easy to understand and fork.