Write down the constraints, not just the goal
"Don't add another payment abstraction" and "preserve the existing analytics events" are the sentences that prevent the rewrite you didn't ask for. Goals are easy to infer; constraints aren't.
Docs & best practices
How to keep project context an agent can actually use.
ContextLoom doesn't run an LLM and doesn't talk to one. It makes no network calls at all. It's the workspace where the context your agent reads and the files your agent writes live — the agent runs in your terminal, as it already does.
Setting up a project
Four steps, none of which change how your agent runs.
- 01
Open the repository, not a folder of notes
Point ContextLoom at the project your agent works in. It finds the project root on its own, respects your root .gitignore, and filters out the churn from .git, node_modules and build directories.
- 02
Set up ContextDB
Use the Set up ContextDB row at the bottom of the sidebar. It creates ContextDB/ and a README inside your project and nothing else. Keeping context in the repository means it's versioned with the code it describes.
- 03
Give your agent the routing rules
During setup, let ContextLoom append the routing rules to your CLAUDE.md or AGENTS.md — it previews the exact text first and only appends. For other tools, paste the same snippet into .cursorrules or whatever config that agent reads.
- 04
Write the first spec yourself
Before the first prompt, put the goal, the constraints and the non-goals in 01_specs/. This is the part an agent can't infer, and it's what makes the difference between code that compiles and code you wanted.
Best practices
Record decisions when you make them
An ADR in 03_decisions/ costs two minutes and saves the same argument three sessions later. Capture the options you rejected and why — that reasoning is the first thing lost when a context window closes.
Log the end of a session
A short note in 08_logs/ — what changed, what's still open — is the cheapest context you can give the next session. It's also what turns a series of one-off prompts into something cumulative.
Prefer appending to rewriting
New file or new section beats overwriting. It preserves how the thinking changed, and it's the rule the agent instructions give your agent too.
Link instead of duplicating
Relative Markdown links between a spec and its architecture doc build a graph your agent can follow. In the preview, you can click them yourself.
Bundle the minimum
Select the handful of files that bear on the question rather than the whole folder. A smaller bundle is easier for a model to use and easier for you to check.
Summarize, don't overwrite
Condense into 04_knowledge/ and leave the source material intact. Summaries are a view; the raw notes stay the source of truth.
Read what the agent wrote
Open the file in Read mode and actually read it. The whole point of keeping a workspace beside the terminal is that agent output stops being something that scrolls past.
Prompt patterns
Patterns that work well against a ContextDB-organized project. Keep the ones you reuse in 05_prompts/ and reference them by path.
Start from the context
Read ContextDB/01_specs/[feature].md and ContextDB/02_architecture/[area].md before writing any code. If they conflict with what you find in the codebase, stop and tell me which one is wrong.
At the start of any task where the spec already exists.
Update architecture from a spec
Read the spec at ContextDB/01_specs/[feature].md. Update ContextDB/02_architecture/[feature].md to reflect the current requirements. Preserve existing sections; add new ones as needed.
When specs have moved ahead of the architecture docs.
Record the decision you just made
We chose [Option A] over [Option B] for [topic]. Write an ADR in ContextDB/03_decisions/ dated today: context, options considered with pros and cons, the decision, and the consequences we accept.
Immediately after a decision, while the reasoning is still in your head.
Close the session
Write ContextDB/08_logs/[today]-session.md: what changed, which decisions were made and where they're recorded, and what's still open for the next session. Keep it under twenty lines.
Before you stop for the day.
Summarize a folder
Read every file in ContextDB/[folder]. Write a summary to ContextDB/04_knowledge/[folder]-summary.md with key points, decisions made, open items, and links to the source files. Do not modify the source files.
When a folder has grown past the point of being skimmable.
Derive the task list
Read ContextDB/01_specs/[feature].md and write ContextDB/todos/[feature].md as a checklist derived from the acceptance criteria. One line per task, no sub-tasks.
When moving from a spec into implementation.
Working alongside agents
What happens if my agent edits a file I'm editing?
Nothing is overwritten. ContextLoom records its own writes, so it can tell them from someone else's. If a file changes on disk while you have unsaved edits, it stops and shows a bar with Reload, Keep Mine and Compare — Compare puts both versions side by side.
Does the tree keep up while an agent writes?
Yes. It refreshes only the directories that changed, so your expanded folders, selection and scroll position survive, and new folders appear. Events from .git, node_modules and other noisy directories are dropped before they reach the tree.
Should ContextDB live inside my repository?
Usually yes. Keeping it in the repo means the context is versioned with the code it describes, travels with a clone, and is there for whichever agent you run next. It's plain Markdown, so it diffs and reviews like anything else.
Does ContextLoom modify my project?
Only when you ask. Opening a project writes nothing. ContextDB setup creates one folder and one README, and appends the agent instructions to CLAUDE.md or AGENTS.md after showing you exactly what they say — and it skips the append entirely if that section is already there.
Agents forget. Files remember.
7-day free trial · Native macOS · Local-first