Getting in and out
Grimling sits beside the chat. The keyboard belongs to either the prompt or the pane, never both.
/grimling opens the pane and gives it the keyboard.- ctrl+x then Tab moves the keyboard from the prompt into the pane. Clicking the pane works too.
- Tab, ↓ and → move forward. Shift+Tab, ↑ and ← move back.
- Esc hands the keyboard back to the prompt.
Typing is safe. While a text box has the focus ring, letters and digits only type. Tab letters and card numbers work again once you Tab out.
Launching an agent
- Move onto a card with Tab or the arrows. Its entry shows: number, category, agent type and what it is for.
- Press Enter on the card, or its number 1 to 9. It becomes the launch target and the cursor jumps to the summon box.
- Type the task and press Enter. The agent starts and gets a live card.
You can also Tab straight to the summon box and type: it launches the current target. If the launch is refused, the task stays in the box.
Template cards are different. Swarm (and any template you enable) never launches anything. It adds a request after your prompt draft so you and the main session decide what runs. Press Esc, then Enter to send it.
The Grimoire
The deck holds three kinds of card.
- Built-ins: Scout (search the code), Builder (multi-step tasks), Planner (design a plan), Fetcher (read a URL), Guide (Claude Code and API answers), and the Swarm template card.
- Your agent files: every agent in
~/.claude/agents and in the project's .claude/agents. A project file wins over a user file of the same name.
- Pack agents: agent packs you list in
cards.packs, shown as <pack>:<name>. v0.1.0 ships no pack of its own; more packs later.
Filter by category with the chips (All, Code, Research, Web, Ops, Swarm, Custom) or press / to filter by name. Card art, short names and categories can be set in ~/.claude/grimling/dex.json.
Recent runs sit under the agents when there is room: your last six distinct launches. Press Enter on one to put its task and agent back in the summon box.
Live agents
- Enter on a running agent opens a message box. Type, then Enter sends it to that agent.
- Enter on a finished agent shows its answer. Enter again adds it after your prompt draft, c copies it, x closes it.
- Answers over 8,000 characters are cut and marked "truncated". If the prompt cannot take the answer, a toast says so and the view stays open.
- An agent that disappears without a final status shows as
gone after about 10 seconds.
x or STOP on a running agent the deck launched opens a Stop / Keep confirm, with Keep under the ring. Grimling stops an agent only when you confirm, and Claude Code's permission check may ask too.
A toast appears when an agent finishes, fails or is stopped, and the status line counts running agents and failures.
Views and buttons
| View | Key | What it shows |
|---|
| Deck | d | Summon box, Grimoire, live agents and recent runs. |
| Flow | f | Which agent spawned which, as a tree. Rows scroll with the ring; "↑ n more" counts rows out of view. |
| Table | t | Every run with status, type and time. |
| Mermaid | m | Copies the agent graph as a Mermaid diagram. |
| Keys | k | Every command, grouped, and any settings problems. |
| Help | h | Starts the tour. |
| Arena | a | Two cards, one puzzle (below). |
The meter
Under the tabs on every view. It mirrors your status line as bars.
ctx: context window used, in tokens.5h and 7d: plan limits, with their reset time.- Session cost, session time and model (and a session count, if you point
meter.sessionsFile at one).
Bars are green, turn yellow from 60% and red from 85%.
Arena
A small proving ground for your cards. Press a or use the Arena button on the bottom row.
- Pick a Red and a Blue fighter with ‹ and ›.
- Pick a puzzle. Each one has a known answer.
- Press Enter on FIGHT. Both fighters run on the same small model (haiku by default).
The correct answer wins. If both are correct, the faster wins; if their times are close, fewer tokens wins; if that ties too, it is a draw. Health bars move only once a fight is scored. Wins, losses and a rating per card are kept in ~/.claude/grimling/arena.json. CLEAR resets a result or a stuck fight. After a scored fight, s copies a small results card to share.
Early scaffold. Puzzles and tie-breaks are still being tuned, so expect more draws than you would like.
Collecting agent types
Every launch, answer, stop and scored fight is logged on your computer in ~/.claude/grimling/runs/, one file a day, redacted by default (log.runs: redacted, full, meta or off). Ask Claude to "collect agent types" and the bundled agent-dex skill reads that log, proposes specialized agents with a card and sprite, and saves only the ones you approve.
All keys
| Key | Where | Does |
|---|
/grimling | Prompt | Open the pane with the keyboard |
/grimling-tour | Prompt | Walk through every key; Esc ends it |
| ctrl+x Tab | Prompt | Move the keyboard into the pane |
| Esc | Pane | Hand the keyboard back to the prompt |
| d f t k | Pane | Deck, Flow, Table, Keys |
| m h a | Pane | Copy Mermaid, Help, Arena |
| 1–9 | Grimoire | Make that card the launch target |
| / | Grimoire | Filter cards by name |
| Enter | Card | Target it, message it, or open its answer |
| c x | Answer | Copy, close |
| x | Running card | Stop it (asks Stop / Keep first) |
/grimling-setup | Prompt | Check, show or set your settings |
/grimling-feedback | Prompt | Preview a report, then open it on GitHub |