A tiny, zero-dependency Python CLI that starts a Claude Code session in a git-tracked project built to work from low information. Say what you want, drop a few files in, or walk away: the agent works out the goal, keeps its transcript in git, and can carry on unattended.
Most sessions don’t start with a clear goal, and a rigid scaffold that assumes one ends up being fought. A cleanvibe 2 project assumes as little as possible. Run cleanvibe (or cleanvibe new [name]) and Claude opens in a fresh private git repo with a first message that explains the deal: the user may say little or nothing and may not be there. The agent reads the chat first, then whatever is in the folder (data_lake/; a brief in there is followed), then the directory name, and keeps its read of the goal in INTENT.md. Thirty minutes in, an intake commits everything as found, moves new material into data_lake/, and the agent plans the work and starts an autonomous loop (straight away if you said nothing, an hour later if you are steering). Every session’s transcript is committed by a hook; sessions are real top-level sessions with Remote Control on, even when an agent started them. Practices for building and researching arrive as skills when the work needs them. Zero runtime dependencies; Windows, Linux, macOS; Python 3.9+.
Bare cleanvibe reopens the project you are in, or creates an auto-named one here; cleanvibe new [name] creates one. A minimal scaffold (CLAUDE.md, INTENT.md, data_lake/, sessions/, skills), a local private repo, and a session with Remote Control on. Thirty minutes in, the data-lake intake runs and the agent gets to work.
Point it at an arXiv, alphaxiv or clawRxiv paper, any other URL, or a folder you drop the paper into, and it scaffolds a standalone replication project: a SKILL.md plan, the paper downloaded locally (gitignored, never committed), the authors’ code as a submodule, and CI that builds a findings site, a PDF report, and a ZIP package. Running anyone else’s code waits for your consent. --batch FILE scaffolds one project per paper in a list.
A read-only audit for drift: done markers left in queue.md, releases missing from devlog.md, outdated skills, references to CLAUDE.md sections that no longer exist, tests with no CI. Exits non-zero if it finds anything.
A read-only pattern scan of code you did not write, before you run it: downloads piped into a shell, eval/exec, destructive commands, credential access, system changes, unusual package sources, binaries, and every host the code mentions. The replication consent gate shows you its summary. A pattern match, not a security review.
Deprecated 1.x mode. Your own investigation of a question. The bootstrap pins the question down with you, runs a literature review into literature/ before building anything, and keeps a themed report in docs/ with a PDF built by CI.
Deprecated 1.x mode. research for when you don’t have a question yet. Give it an area with --area; a topic-finding loop drafts and scores candidate questions with you, records them in topics/, and settles on one before the literature review.
Deprecated 1.x mode. A git-tracked conversation about one topic: research-heavy, light on code, in a private repo. It opens by asking what you are trying to do, keeps conclusions in notes/, and a hook commits every session’s transcript into sessions/.
Deprecated 1.x mode. Onboard an existing repo. Works on a dedicated cleanvibe-onboarding branch — the default branch is untouched. Prepends scaffold if files exist; never overwrites.
Deprecated 1.x mode. In-place onboarding for a project you are already in: injects only the scaffold files that are missing. An existing TODO, ROADMAP.md or BACKLOG.md is kept and becomes the basis of todo.md. Non-destructive by contract.
Semantic versioning (currently v2.0.0). cleanvibe, new, replicate, doctor and legacy are stable within 2.x; replicate behaves as in 1.x and the legacy modes are frozen. A new project always has CLAUDE.md, README.md, INTENT.md, .cleanvibe.json, sessions/, data_lake/, the transcript hook and the intake script, in a repo on main with no remote. new never overwrites a project; zero runtime dependencies is a hard guarantee. Preview anything with --dry-run.