> ## Documentation Index > Fetch the complete documentation index at: https://docs.usegandalf.com/llms.txt > Use this file to discover all available pages before exploring further. # gandalf distill and suggest: turn sessions into skills > Distill what you worked out with your coding agent into lessons, then group the lessons into skill drafts you can review and install. 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 ```bash theme={null} gandalf distill [--since ] [--limit ] [--agent claude-code|codex] [--dry-run] gandalf suggest [--agent claude-code|codex] [--fresh] [--dry-run] gandalf tui # review drafts: a approve, x dismiss gandalf skill add ~/.gandalf/distill//drafts/ --scope project ``` 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`. | Flag | Description | Default | | - | - | - | | `--since ` | Only sessions changed in the last N days. | `30` | | `--limit ` | At most this many sessions per run. | `5` | | `--agent ` | Only sessions from this agent (`claude-code` or `codex`). | both | | `--dry-run` | List the sessions that would be sent, with trace sizes, without calling the agent. | off | 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`). ```text theme={null} 2026-10-13 Analyse plot's UX/UI and user stories, then implement ... 8 lessons ยท $0.18 medium User-facing vocabulary: Automations, Connections, Contents medium Bulk copy renames break tests that query by label low ESLint forbids synchronous setState in effects; use queueMicrotask ``` ## 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//drafts//`, 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.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: ```bash theme={null} gandalf skill add ~/.gandalf/distill/plot-558ad3b3/drafts/ui-copy-conventions --scope project --dry-run gandalf skill add ~/.gandalf/distill/plot-558ad3b3/drafts/ui-copy-conventions --scope project ``` 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. ## Related * [`gandalf skill`](/cli/skill) * [Trust contract](/trust-contract) This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.