DocsBest practices›

Docs · Workflow

Best practices

Fulcrum gives you tools that touch your filesystem, your shell, and your inference budget. Most of the patterns here come from how the agent loop actually behaves, plus failure modes that surface when sessions go sideways. They are opinionated by design — pick the ones that fit, ignore the rest, but read the "Common mistakes" section before you skip ahead.

Project setup

  • Write a CLAUDE.md at the repo root before starting serious work. Without one, Fulcrum loads no project context — only your global memory and bundled skills. AGENTS.mdis the open-standard variant and is also picked up; if both exist, both are loaded. Cover conventions, do/don't lists, the planning folder convention, and any tools the agent should always reach for (e.g. an MCP server like GitNexus).
  • Pin the model in ~/.fulcrum/config.json. The default is MiniMax-M2.5, set by the model field. If your team agreed on a different model on scx.ai, set it once and persist — /model <id> writes back to the same file. Also pin vision_model, transcription_model, and tts_voice if you care about consistency.
  • Use /doctor after first install. It checks that config is readable, that api_key (or your fulcrumcode.app session token) is set, and that the gateway base URL is reachable. Three pass lines means you're good.
  • Use /whoami to confirm tier + monthly cap. It hits fulcrumcode.app, returns your email, tier, status, cap, and percentage used so far this month. Run it before kicking off heavy multi-agent work — caps surface here long before they surface as a 429.

The "big edit" pattern

For multi-file refactors, dispatch a sub-agent with the Agent tool — and run it in an isolated worktree.

  • Clean context. The sub-agent gets its own system prompt and tool allowlist from a profile in ~/.fulcrum/agents/. None of your main-thread back-and-forth pollutes its window.
  • Parallelism. You can fan out — review, tests, docs — and merge the outputs after. The main agent keeps coordinating.
  • Isolated worktree. The EnterWorktree tool spins up a git worktree so a bad refactor never trashes your dirty working tree. ExitWorktree unwinds it. Two simultaneous sessions on the same non-isolated tree is a corruption risk worth avoiding.
  • Verify the diff before merging. Run git diffon the worktree branch yourself. The sub-agent's self-report is a hint, not a contract.

The "long-running command" pattern

  • Builds and tests over ~30s: run with run_in_background: true. The Bash tool returns immediately and the TUI keeps taking input. Fulcrum is notified when the command finishes and picks up the output then — you're not blocked the whole time waiting for a webpack build.
  • Streaming logs: use the Monitor tool. Monitor tails a long-running process with a filter regex and emits one event per matching line. It does not spam your context with every log line — only the matches land in history. Good for "wait until the deploy saysREADY".
  • Polling: use until, not sleep in a loop. until <check>; do sleep 2; done exits cleanly when the condition is met. Long leading sleep commands are blocked by the Bash tool on purpose — they signal a polling pattern that should be done with Monitor instead.

The "destructive operation" rule

Fulcrum prompts before Bash and Edit by default. The TUI binds a chord to toggle auto-approve — defaults are visible via /keys. Turn auto-approve OFF before any session that touches:

  • git push --force, git reset --hard, git branch -D
  • rm -rf against anything outside a sandbox directory
  • Schema migrations, especially prisma db push
  • Anything against production credentials or a production database
  • Publishing to npm, PyPI, or a container registry

The approval gate is the cheapest insurance you have. Skip it only when the cost of the wrong move is recoverable.

Don't fight the tools

  • If Fulcrum reads a file you didn't expect, that's intentional. It cross-checks claims against ground truth before acting. Let it. Re-prompting "just trust me" usually wastes a turn.
  • Edit refusing on multiple matches is a feature. The old_string uniqueness check exists because silent application against the wrong location is the worst failure mode in a refactor. Give it more context, not less — quote the surrounding line.
  • Bash output looks weird? Run the same command in a separate terminal. Compare. Don't keep arguing with the agent over a shell quirk you can verify in five seconds outside the TUI.
  • Don't rename via find-and-replace. If the project has GitNexus or another call-graph tool wired in via MCP, use the rename action — it understands references the way text-search doesn't. The bundled refactor skill lays out the find → read → plan → apply → verify loop the agent should follow.

Memory hygiene

  • Memories go stale. ~/.fulcrum/memory/MEMORY.md is an index loaded into the system prompt at session start; the per-topic files behind it are loaded on demand by the ReadMemory tool. Anything older than three months should be re-verified against the codebase before you act on it.
  • Never put secrets in memory. Secrets belong in the OS keychain (macOS Keychain, GNOME Keyring, Windows Credential Manager) via keyring, with an encrypted-file fallback at ~/.fulcrum/scx.enc. The scx.ai key lives there on purpose — outside the memory tree, outside config.json. Project secrets go in .env files the agent already knows to ignore.
  • Memory is a hint, not a contract. When a memory says "the X function lives at src/Y.py:42", grep before relying on it. Files move, line numbers drift, and Fulcrum will happily edit the wrong location if you don't verify.
  • Use SaveMemory deliberately. The agent has a SaveMemory tool that writes a topic file and updates the index. Tell it "remember that we use pytest, not unittest" and it will. Don't confuse this with /btw— that's a side-question that snapshots history, not a memory save.

The cost question

  • /cost shows tokens + estimated USD per session, broken down by model. Run it whenever a session has been open longer than "a quick question".
  • Heavy tool work burns tokens. WebFetch over a large page, Grep across a big monorepo, and multi-file Reads each push real token volume into the next model call. Fulcrum collapses consecutive read-only calls into a ● Searched (N) group in the transcript for readability — but the underlying input cost is still there. Narrow your prompts.
  • Use /compact before context fills up. /contextreports current vs. threshold; when you're approaching the threshold, compact summarises the middle of the transcript so the next turns aren't re-billed for old context. Cheaper than starting a new session and reloading state.
  • Subscription caps and top-ups. /whoamishows your monthly token cap and how close you are. If you're hitting it, top-up packs at /subscribe are AUD inc-GST one-shots that don't expire while your subscription is active.

Common mistakes

Real ones, observed across Fulcrum sessions and saved into memory after the user pushed back.

Two sessions on the same working tree

Two Fulcrum (or Claude Code) sessions editing the same checkout simultaneously corrupts the tree — one writes while the other's reading a stale version. Use git worktree add (or the EnterWorktree tool) to give each session its own checkout.

Renaming without grepping the whole repo

When you rename a package or symbol, the agent consistently misses one of: Dockerfile, CI workflow files, helm charts, lockfiles, or build cache tags. Always ask Fulcrum to grep the entire repo after a rename — including non-source files — and verify before you push.

Running migrations from a stale environment

Running schema migrations from a long-lived shell, pod, or container can apply against the version baked into the image, not the version you just pushed. Always run migrations from a fresh process, against the currently-deployed code. The agent will follow whatever shell context you give it; that context can lie.

Trusting py_compile as a test

py_compile only catches syntax errors. It will not catch UnboundLocalError, NameError, or any closure / scope bug. If you ask Fulcrum to "verify the file is fine", it'll lean on the cheapest check — make it run the actual code path.

Provider key shapes don't match

Different inference providers use different key prefixes — scx.ai keys start with sk-scx-, others use their own prefixes. If you switch base_url without rotating the key, requests fail with auth errors that look like rate limits. /doctorcatches the "unreachable" case but not the wrong-provider case.

Awaiting heavy work in a shutdown handler

If you're hooking Fulcrum's session-end or pre- shutdown handlers, don't await a slow operation inside them. The harness has a hard timeout (on the order of 10s) — anything longer gets cut off and you lose the work. Fire-and-forget the slow part; finalise the cheap part synchronously.

Next steps