A starting point for a scientific Python project, wired for Claude Code.
This repository is a GitHub template. Click Use this template, or:
gh repo create marl-playground --template tommybotch/project-template --private --clone
cd marl-playgroundThe name given here becomes the project's name. A one-shot workflow in the new
repository substitutes it for the [PROJECT_NAME] placeholders, replaces this
README with a short project one, and then deletes itself. It runs on the first
push; if it has not run, start template cleanup from the repository's
Actions tab.
Then follow the Quick Start below.
Run once per machine; safe to re-run.
bash setup_claude_tools.shInstalls:
| Tool | Role |
|---|---|
| graphify | Semantic knowledge graph over code and docs — query structure instead of grepping |
| caveman | Output compression, roughly 65% fewer output tokens, plus the cavecrew subagents |
| RTK | Shell output compression through a PreToolUse hook |
| superpowers | Brainstorm → spec → plan → TDD workflow gates |
Also installs Claude Code, Node.js (required by caveman's hooks), and uv, when they are missing.
The script probes what the machine can do rather than detecting a named environment, so the same file works on macOS, a RunPod container, a non-root Linux workstation, and an HPC login node.
| Flag | Effect |
|---|---|
--check |
Print the environment probe table and tool status; change nothing |
--prefix PATH |
Install root (default: $CLAUDE_TOOLS_PREFIX, then a writable /workspace, then $HOME) |
--extra-dir PATH |
Repeatable; grants Claude access to another directory |
--non-interactive |
Never prompt |
--skip-all |
Skip every install step; performs only the persistence symlink |
--skip-claude, --skip-auth, --skip-node, --skip-plugins, --skip-rtk, --skip-uv, --skip-graphify, --skip-perms |
Skip one step |
Start with bash setup_claude_tools.sh --check to see what it would target.
The script writes outside this repo. Everything it touches is user-level — it never writes project-scoped Claude config, so permissions stay a decision you make for your own account rather than something a cloned template grants you.
| Path | What lands there |
|---|---|
~/.claude/CLAUDE.md |
A tool-routing block — how to use graphify and RTK. Written between <!-- claude-tools:start --> and <!-- claude-tools:end --> |
~/.claude/settings.json |
The RTK PreToolUse hook, and any --extra-dir paths |
~/.claude/hooks/rtk-rewrite.sh |
The RTK hook wrapper |
~/.local/bin/ |
rtk, uv, graphify (or your --prefix) |
To see the routing block it installed:
sed -n '/claude-tools:start/,/claude-tools:end/p' ~/.claude/CLAUDE.mdAnything you write outside those two markers is yours and is preserved. Re-runs
replace only the block between them, leaving the rest of the file — your own notes,
other tools' sections, @ imports — untouched and in their original order. To change
what goes inside the block, edit routing_block_content() in setup_claude_tools.sh;
editing between the markers by hand is overwritten on the next run.
On a container with an ephemeral home directory, the script keeps Claude's
config on the persistent volume and symlinks ~/.claude to it. After a restart,
bash setup_claude_tools.sh --skip-all restores the link in under a second.
uv sync # creates .venv from pyproject.toml
source .venv/bin/activate # or: uv run python script.pyuv.lock is deliberately not committed to the template, so each project
resolves its own dependency versions on this first sync. Commit the lock file
it produces.
code/utils/config.py detects BASE_DIR automatically. Override the rest with
environment variables when your data lives elsewhere:
DATASETS_DIR— raw dataSCRATCHorTMPDIR— intermediate files
graphify . # extract code into graphify-out/graph.json
graphify cluster-only . # cluster and name communities, write GRAPH_REPORT.md
graphify install --project # register the skill in .claude/skills/Claude then answers structural questions from the graph instead of reading files.
graphify-out/ is gitignored — it is regenerable from source.
Four tools, each solving a different problem. Two of them cost you nothing to use — they work through hooks. The other two you invoke deliberately.
| Tool | The problem | What you get |
|---|---|---|
| graphify | Grep answers "where does this string appear." It cannot answer "what breaks if I change this." | A queryable graph of your code's structure |
| superpowers | Agents jump to code before the problem is understood, then declare success without checking. | Workflow gates: design before code, evidence before claims |
| RTK | A single git diff or test run can flood the context window with output nobody reads. |
60–90% smaller command output, automatically |
| caveman | Verbose prose burns output tokens without adding information. | ~65% fewer output tokens, same technical content |
Build once per repo (step 5 above), then re-extract after significant changes:
graphify update . # re-extract, no LLM needed
graphify watch . # or rebuild automatically as you editThe queries worth knowing:
graphify query "how does preprocessing feed the model?" # traverse from a question
graphify affected "load_subject" # what breaks if I change this
graphify explain "run_pipeline" # plain-language node summary
graphify god-nodes # the architectural hubs
graphify path "load_data" "save_results" # how are these connectedUse the graph for structure, grep for text. "Who calls this function" is a graph
question. "Where does the string subject_id appear" is a grep question. Asking the
wrong tool wastes a lot of context.
The core idea: separate deciding what to build from building it, and require evidence before any success claim. The main path:
brainstorming → writing-plans → subagent-driven-development → code review
(design) (task list) (execute + review)
/superpowers:brainstorming— before any feature. Asks questions one at a time, proposes approaches, and will not write code until you approve a design. Bounded changes get a short design in chat; new subsystems get a written spec./superpowers:writing-plans— turns an approved spec into numbered tasks, each with exact files, real test code, and a commit. No "TBD", no "add error handling."/superpowers:subagent-driven-development— runs the plan with a fresh agent per task and an independent reviewer after each. Catches what a single long session stops noticing./superpowers:test-driven-development— write the failing test, watch it fail, then implement. The "watch it fail" step is what proves the test works./superpowers:systematic-debugging— for any bug, before proposing a fix./superpowers:verification-before-completion— run the command, read the output, then claim success. Not before.
When to reach for it: multi-step work where being wrong is expensive. For a one-line fix it is overhead — say so and skip it.
A PreToolUse hook rewrites Bash commands through rtk for you. Write commands
normally. To see what it saved:
rtk gain # token savings this session
rtk gain --history # per-command breakdownOccasionally useful directly: rtk err <cmd> (errors only), rtk test <cmd>
(failures only), rtk diff (changed lines only).
One conflict to know about: don't run RTK alongside a second tool that also
registers a PreToolUse hook on Bash — they compete to rewrite the same
command. Pick one.
Active by default. Adjust when it gets in the way:
/caveman lite | full | ultra | off
/caveman-stats # tokens and dollars saved
It also ships subagents that return compressed findings — cavecrew-investigator
to locate code, cavecrew-reviewer to review a diff — which keeps the main
conversation smaller on long sessions.
1. "Index this project" → graphify builds the graph
2. /superpowers:brainstorming → agree on a design before code exists
3. /superpowers:writing-plans → the design becomes reviewable tasks
4. Execute → RTK shrinks command output, caveman shrinks prose
5. /code-review → independent check before merge
The pattern: graphify answers what the code is, superpowers governs how work proceeds, RTK and caveman keep the context window from filling up while it happens.
The tool setup script has its own suite — plain bash, no framework, no network:
bash tests/test_setup_claude_tools.shIt covers the environment probes, flag parsing, JSON merging, and the marker-block
rewriting that keeps ~/.claude/CLAUDE.md idempotent across runs.