Skip to main content
Much of what you teach an agent during a session is lost when the session ends: which command actually works in this repository, what a confusing error really meant, which wording you corrected three times. gandalf distill reads your recent sessions and asks your own coding agent what a fresh agent would need to be told next time. gandalf suggest groups those lessons by area of work and drafts a skill for each. gandalf tui shows the drafts in an inbox where one key installs or dismisses them. Nothing is sent to Gandalf. Redacted excerpts of a session go only to the agent the session came from, run non-interactively on your own subscription.

​
Synopsis

Run both from the repository you worked in. Lessons and drafts are kept per project.

​
distill

Finds the Claude Code and Codex sessions for the current project, builds a short trace of each, and asks the agent each session came from for lessons: Claude Code sessions go to claude -p, Codex sessions to codex exec. What goes into a trace:
  • what you typed, with injected context removed
  • short excerpts of what the agent said
  • every command that failed, with its error, and the steps right after it
  • commands that succeeded, file edits, and other tool calls, collapsed into counts
Paths, URLs, email addresses, long tokens, and key=value secrets are redacted before anything leaves the machine. A trace is cut to roughly 6,000 tokens, keeping your messages and failures first. A session is skipped when it has fewer than two typed messages, when it has already been distilled, or when it is a resumed copy of a conversation that was already distilled. Codex runs with --ephemeral, a read-only sandbox, and your default model. If your account cannot use that model non-interactively (codex exec hi fails), set GANDALF_CODEX_MODEL to one it can. Each session costs about $0.15 on a Claude Code subscription and takes 15 to 20 seconds. The run prints each lesson with how much time that session lost for lack of it (high, medium, low).

​
suggest

Groups every stored lesson for the project by the area of work an agent would need it in, and decides where each group belongs:
  • skill: knowledge for one area, loaded only when a task matches. A SKILL.md is drafted and written to ~/.gandalf/distill/<project>/drafts/<name>/, with a provenance.json listing the sessions and lessons it came from.
  • rule: a short instruction that applies to nearly all work. Printed for you to copy into CLAUDE.md or AGENTS.md.
  • dropped: a one-off, a tooling artifact, or something any capable agent already does.
Each group also carries a scope: this repository, you everywhere, or this machine (for tools installed on your computer). --dry-run groups the lessons without writing drafts. A run costs about 0.15forthegroupingplus0.15 for the grouping plus 0.05 per drafted skill. Grouping is a model call, so Gandalf keeps the previous result in groups.json and shows it to the agent on the next run: group names and destinations stay put unless a new lesson changes the picture. --fresh ignores the previous grouping. --agent picks which agent groups and drafts; the default is the one most lessons came from. Each draft records where it came from in provenance.json: the session ids, the lesson titles, and the date. When every lesson came from a single session the draft is marked seen once with a re-check date 30 days out. gandalf skill list and gandalf skill show flag installed skills whose re-check date has passed, so facts that described a passing state get looked at again.

​
Reviewing drafts

gandalf tui opens the inbox without the background service:
  • Inbox lists the drafts for this project with how many sessions and lessons each came from; the preview shows the SKILL.md.
  • a installs the selected draft into this project for every detected agent (the same as gandalf skill add --scope project) and moves it to approved/; x moves it to dismissed/. Nothing is deleted.
  • Skills lists what is installed and whether every agent has the same copy. tab switches panels, ? explains the flow.
gandalf tui --work opens the work browser instead; that one needs the service.

​
Installing a draft

Drafts are ordinary skills. Read one, edit it if you like, and install it like any other:
A project-scoped skill lands in .claude/skills/ and the shared .agents/skills/ of the repository, which Claude Code, Codex, and Cursor all read. Commit it so teammates get it too.

​
What to expect

  • Lessons that come from a single session may describe temporary state. Drafts mark these in a “Seen once” section and carry a re-check date; gandalf skill list reminds you when it passes.
  • Grouping is anchored on the previous run, so names and destinations stay stable; --fresh starts over.