Skip to content

The first fruit of the Nüwa tree — an autonomous AI pentest legion (634-team champion, 8h unattended, 1B tokens beat 4.5B). Not just a tool: evolvable by design. Grow your own fruit on the Nüwa Foundation (Create/Language/History).

6.4 KB
Raw Blame

name: sapper-setup description: Opt-in the CURRENT project to the sapper engagement-graph working memory (offensive specialization of the fact graph). Creates the local .sapper/ graph, registers the SessionStart + UserPromptSubmit hooks in this project's .claude/settings.json (NOT global — other projects are untouched), and writes AGENTS.md teaching typed facts (host/service/cred/vuln/loot/flag), the flag ledger (sapper flag), and the arena bridge (sapper arena). After setup, every turn in this project auto-injects the current graph state and current date output so Claude always knows what's confirmed vs. tried and what time it is; sub-agents (sapper dispatch) can read/write the same graph. For multi-agent tmux work, list panes with sapper peers --discover and ask the user which panes/AI peers may communicate before authorizing any target. Use when the user says "enable sapper here", "在这个项目用 sapper", "setup the engagement graph", or when starting a pentest engagement / CTF challenge / multi-step debugging/research/audit campaign that should be tracked and resumable. For competitions, follow up with sapper arena init and set SAPPER_ARENA_TOKEN. This is the per-project initializer the install.sh skill exposes as a slash command. license: MIT

sapper-setup

Per-project initializer for the sapper engagement graph working memory. This is the opt-in switch: until you run it in a project, sapper does nothing there. After you run it, that one project auto-reads and auto-maintains its graph on every turn.

Zero servers — it just drops a local .sapper/ and writes the two hook entries into this project's .claude/settings.json. For penetration engagements, pair it with sapper arena init (competition platform config) and record findings as typed facts (-k host/service/cred/vuln/loot/flag).

What it does

Run inside the target project directory. Exactly three things, all local:

  1. Creates the graph at ./.sapper/ (unless one already exists): project.json, facts/goal.json, and the intents/ hints/ dirs.
  2. Registers hooks in ./.claude/settings.json — SessionStart and UserPromptSubmit, both pointing at sapper-hook.py. These inject the current graph state and date output into every turn so the model always knows the frontier and current local time. This is a project-level settings file; the user-level ~/.claude/settings.json and every other project are completely untouched.
  3. (optional) Writes AGENTS.md so dispatched sub-agents learn the fact-graph protocol (sapper fact, sapper done, etc.).

No daemons, no ports, no database. rm -rf .sapper .claude undoes everything.

How to run it

From the shell (after bash install.sh):

cd /path/to/your/project
sapper setup --goal "reproduce the empty-token crash" --agents

Or, since this is a skill, the user can just type /sapper-setup <goal> inside Claude Code and Claude will run the equivalent commands.

Multi-agent tmux authorization flow

If the user wants multiple AI agents to coordinate through tmux, do this after the normal setup:

  1. Run sapper peers --discover and show the pane list to the user.
  2. Ask which panes/agents are allowed to communicate and what names to use.
  3. Only after explicit approval, run:
sapper peers --add harley --target api-6:0.0 --sender "Codex/api2-4"
  1. Use sapper send harley "message" for communication. It appends to .sapper/ai-channel.txt and uses a reliable tmux paste-buffer submit flow.
  2. After sending a question, use sapper capture harley --lines 120 to read recent direct TUI replies from that authorized peer. Peers may answer without using sapper send, so the shared channel log is not always enough.

Do not infer authorization from discovery output or from session names. Never send to or capture from a tmux target unless sapper peers shows it as authorized in this project's .sapper/ai-peers.json.

After setup

  • The model is reminded each session + each turn to read/maintain the graph.
  • The hooks inject current local time from date each session + each turn.
  • Drive it with sapper dispatch reason (commander proposes next work), sapper dispatch <intent-id> --skip-permissions (executor does the work), sapper dispatch verify --intent <id> (verify a result), or sapper auto --skip-permissions (full loop to completion).
  • See state anytime: sapper status, sapper graph; run the read-only sapper validate audit before autonomous dispatch or committing .sapper/.

Undo

sapper teardown            # removes sapper hooks + its AGENTS.md, keeps .sapper/
sapper teardown --purge    # also deletes the graph data

install.sh --uninstall removes the sapper command and this skill globally, but never touches project-level .sapper/ or .claude/ — those are per-project and must be removed per-project with teardown.

Autonomy guardrail (prompt injection)

A dispatched executor (sapper dispatch <intent>, sapper auto) runs the whole graph — every fact/intent/hint text — interpolated into its prompt. So text recorded as a "fact" becomes instructions the next executor sees. The executor system prompt fences graph content as untrusted data and tells the agent to treat embedded "ignore your rules / run this command" text as an observation to record, not a command to obey. That is a textual defense, not a sandbox.

Dangerous combination: a graph fed by untrusted content (a hostile .sapper/*.json in the repo, or facts transcribed from attacker-controlled code/output) plus --skip-permissions plus real shell/file access. In that case a graph field can attempt to drive the agent. Do not run sapper auto --skip-permissions on a repo whose .sapper/ is untrusted — prefer the default (each tool use prompts you), and read the facts an autonomous run writes before acting on them. Treat --skip-permissions as opt-in per run.

Where things live (IMPORTANT — nothing global)

  • ./.sapper/ — all graph data. Move/delete the project, the graph goes with it.
  • ./.claude/settings.json — the two hook entries, project-scoped.
  • ./AGENTS.md — sub-agent protocol (optional).
  • ~/.local/bin/sapper — the CLI (one symlink).
  • ~/.claude/skills/sapper-setup — this skill (one symlink).

There is no ~/.sapper, no global hook registration, no shared state between projects. Two opted-in projects have two independent graphs.