DocsPrompting›

Docs · Workflow

Prompting

Fulcrum is a coding agent with around 36 built-in tools sitting on top of ~/.fulcrum/ and your shell. A good prompt makes the agent use those tools— read files, run searches, execute the failing test — rather than answer from memory. The patterns below come from the way Fulcrum's system prompt and tool surface are wired: it expects ground-truth inputs (paths, repros, hypotheses) and rewards prompts that give them.

Anatomy of a strong prompt

A weak prompt makes Fulcrum guess. A strong prompt narrows the search to a path and a repro, so the first tool call is already on the right file.

Weak

fix this bug

No path, no repro, no scope. The agent grep-spirals across the repo and burns tokens locating the problem before it can solve it.

Strong

tests/test_auth.py::test_token_refresh
fails with TypeError on line 42.

Repro: pytest tests/test_auth.py -k token_refresh

Yesterday's change was in src/auth.py
near line 40. Find the cause and fix it
— don't refactor anything else.

Path, reproduction, hypothesis range, scope constraint. Fulcrum opens the file, runs the test, reads the trace, edits, re-runs.

Four ingredients to copy: path (a file or symbol so Read goes first, not Grep), repro (the exact command Fulcrum can run via Bash to see the failure itself), hypothesis(a region to look at, even if vague — "line ~40" beats nothing), and scope("don't refactor anything else" is a hard constraint Fulcrum will respect).

The four kinds of work

Most coding agent requests collapse into one of four shapes. Each one wants a slightly different prompt.

Exploration — "how does X work?"

Use the words explore or trace. Fulcrum will reach for Grep, Glob, Read, and Ls. Consecutive read-only calls collapse into a single ● Searched (N)tree in the transcript, so you can let it cast a wide net without spamming context. Give the symbol or concept name; don't pre-narrow the search — let it see widely.

trace how the auth middleware verifies
JWTs. Start at the request handler in
src/server.ts and follow the call chain.

Editing existing code

Be specific about where and what. Fulcrum's Edit tool refuses to apply when old_stringmatches more than one location in a file. That refusal is a feature, not a bug — give it more context (a uniquely-quoted surrounding line) rather than less. If you're renaming across files, hand it the old name and the new name in the same prompt.

in src/queue.ts, change the default of
maxRetries from 3 to 5. Don't touch
anything else.

Building new code

Describe the contract before the implementation: input shape, expected output, where it integrates. Then say no extrasif you want a tight, scope-limited result. Without that constraint, Fulcrum will tend to over-engineer — adding logging, validation, and helpers you didn't ask for. Pointing at an existing module to match style is usually faster than describing the style in prose.

add a /healthz endpoint. Inputs: none.
Output: a JSON body with uptime + git
sha. Match the style of the existing
/version handler. No new dependencies,
no config keys.

Investigation / debugging

Give the failure mode plus the smallest repro you have. Fulcrum will instrument, run via Bash, and read the trace itself — don't pre-diagnose unless you're confident, because a wrong hypothesis will pull the agent off the actual cause. If you have a stack trace, paste the top frame; if you have a log file, point to the path instead of pasting the whole thing.

/voice cuts off after ~3s on macOS but
works on linux. Repro: run `fulcrum`,
type /voice, speak. Logs at
~/.fulcrum/logs/fulcrum.log show the
recorder closing early. Find why.

Things that consistently waste tokens

  • "Make it production-ready." Too vague. Fulcrum's default reading is "add logging, error handling, retries, type hints, and tests," which is rarely what you meant. Say which property you mean (logging? error handling? observability? coverage?) and which you don't.
  • Asking for "best practices" without context. The agent will load whatever it thinks they are. Better: point at a file and say "match this style". If you want a real review, run the bundled refactor skill or invoke a sub-agent profile from ~/.fulcrum/agents/.
  • Restating CLAUDE.md content. Fulcrum reads CLAUDE.md and AGENTS.md from your repo root at session start and injects them into the system prompt via _ensure_system_prompt in agent.py. You don't need to repeat "use pytest" if it's already in there. Verify what it loaded with /memory.
  • Pasting huge logs. If the file exists locally, reference it (./logs/fulcrum.log) and let Fulcrum Read it on demand. The Read tool only pulls the slice it needs and doesn't push the whole file into history.
  • "Refactor the whole module." Without scope, the agent rewrites more than you wanted and the diff becomes unreviewable. Pick one symbol or one file per turn; chain them.

Mid-conversation moves

Slash commands run client-side in the TUI — they don't burn a model turn. Use them to steer without re-prompting.

CommandWhat it does
/cancelAbort the in-flight agent turn but keep queued messages. The next queued item starts immediately. Ctrl+C does the same.
/clearReset the conversation history. Memory and config are untouched.
/compactSummarise the middle of the transcript via the model to free context. Use it when /context says you're approaching the threshold.
/btw <question>Fork a side question off the current turn — Fulcrum reuses the active context to answer, then rolls history back so the main thread stays clean. Not a memory save: the agent's own SaveMemory tool persists facts.
/costShow accumulated token + USD usage for this session, broken down by model.
/contextShow current history tokens vs. the compaction threshold. Drives the call on whether to /compact.
/filesList file paths Fulcrum has read or written this session, scraped from recent tool-call arguments.
/historyList the last 10 saved sessions (each session is a transcript snapshot under ~/.fulcrum/sessions/).
/memoryPrint the contents of ~/.fulcrum/memory/MEMORY.md — the index the system prompt loads at session start.
/skillsList all loaded skills, tagged by origin (bundled, ~/.claude, ~/.fulcrum).
/statusShow model, endpoint, cwd, history length, and an estimated token count.

Run /help in the TUI for the full list — a fresh install registers around 37 commands across builtins and the MCP plugin.

Estimating work

When you plan with Fulcrum, estimate in three quantities, not human time:

  1. Million tokens — rough total budget (input + output) to finish the task. Visible in /cost as you go.
  2. Concurrent agents — how many sub-agents run in parallel. The Agent tool dispatches profiles from ~/.fulcrum/agents/ and ~/.claude/agents/ in isolated context windows.
  3. Wall-clock time — how long those agents run for. The only form of "time" worth quoting.

Example

"MVP scope: ~8M tokens, 6 concurrent agents, ~25 min agent wall-clock. V1 scope: ~40M tokens, 12 concurrent agents, ~90 min agent wall-clock."

Why: token budget is the real cost ceiling, concurrency decides shape, and wall-clock falls out of the two. Quoting "a few hours" tells the agent nothing it can act on.

Multi-turn workflows

Two affordances let you go past a single turn cleanly:

  • Skills. A skill is a markdown file with YAML frontmatter — name, description, and the steps Fulcrum should run. Bundled skills ship inside the binary (e.g. refactor); user skills go in ~/.fulcrum/skills/. The agent invokes them by name (/skillslists them) or matches them by description against your prompt. Use a skill to package a recurring shape — a 4-step refactor, a code-review checklist — so you don't restate it every time.
  • Sub-agents. The Agent tool dispatches a named profile with its own system prompt, tool allowlist, and model. Profiles live in ~/.fulcrum/agents/ (and ~/.claude/agents/ for compatibility). Use them to parallelise: one agent reviewing security, one writing tests, one updating docs — all in isolated context windows so the main thread stays focused.

Next steps