How to use ContextLoom

From install to a project your agent can navigate, in about five minutes.

01

Install ContextLoom

Download from the Mac App Store and open it. macOS 13 Ventura or later.
02

Open your project folder

Choose Open a Project Folder (⇧⌘O), or drop a folder onto the window. The sidebar shows the project — Markdown, source, config and .env files — minus what your .gitignore excludes and noise like .git and node_modules. Opening a single file finds the repository it belongs to, so you get the whole project rather than one subfolder.
03

Set up ContextDB

A row at the bottom of the sidebar offers to set it up. It creates one folder and one README, shows you the exact agent instructions first, and can append them to your CLAUDE.md or AGENTS.md. Nothing else in your project is touched — and nothing happens until you ask.
04

Let your agent work

Run Claude Code or Codex as you normally would. Files land in the tree as they're written, without your open folders collapsing. If your agent changes a file while you have unsaved edits, ContextLoom stops and offers Reload, Keep Mine, or Compare rather than picking a winner.
05

Read, edit, and bundle

Open any file in Edit, Split, or Read mode. When you need to hand context to a chat window, tick the files in the sidebar and press ⇧⌘B — they're copied as one block, each under its own path heading. Secret files are always left out.

The ContextDB taxonomy

ContextLoom recommends this structure and writes it into your agent instructions, so files land in predictable places. It's a convention, not a cage — the folders are created on first use, and you can organize however you like.

00_index/

Entry points, overviews, project maps.

Keep a map here that summarizes the project and links to the key docs.

01_specs/

Requirements, PRDs, feature specs.

Use when defining what needs to be built. One spec per file.

02_architecture/

System design, data flow, components.

Use when detailing how something will be built. Link back to the spec.

03_decisions/

Architecture Decision Records, tradeoffs.

Use when a decision is made. Record the context, the options, and the consequences — this is what an agent can't reconstruct later.

04_knowledge/

Reusable concepts and explanations.

Use for condensed overviews and domain reference. Write summaries here rather than overwriting the source material.

05_prompts/

Reusable prompts and system instructions.

Use for prompts you run more than once, so they can be referenced by path.

06_agents/

Agent roles, rules, memory.

Use for the rules a given agent should follow on this project.

07_diagrams/

Mermaid diagrams, one per file.

Use for flowcharts and sequence diagrams kept as text beside the docs they belong to. ContextLoom renders them in the preview.

08_logs/

Append-only logs, session summaries, changelogs.

Use at the end of a session to record what happened — this is what makes the next session cheaper.

99_scratch/

Drafts, temporary thinking, WIP notes.

Use for anything uncategorized. Process or delete it regularly.

todos/

TODO lists and task tracking.

Use for tracking work. Keep each file focused — one per feature or sprint.

Naming conventions

Numeric prefixes preserve intentional ordering and make traversal predictable
snake_case for folders: 01_specs/, 03_decisions/
kebab-case for files: checkout-redesign.md, payments.md
Date-prefix when chronology matters: 2026-02-07-auth-decision.md
Plain Markdown only (.md, UTF-8), with a # Title heading in every file
Prefer small, composable files over large monoliths

The agent instructions

This is the routing ruleset ContextLoom appends to your CLAUDE.md or AGENTS.md when you set up ContextDB — shown here so you know exactly what goes in. The app previews it first, only ever appends, and skips the whole thing if the heading is already there. You can also paste it yourself, into .cursorrules or any other agent config.

CLAUDE.md / AGENTS.md

## ContextDB — Project context repository

This project uses a `ContextDB/` directory (managed by ContextLoom) as a local context repository. It is the **canonical place** for all long-lived project context.

### Folder Taxonomy

ContextDB/
├─ README.md          ← ContextDB overview (do not modify)
├─ 00_index/          ← Entry points, overviews, maps
├─ 01_specs/          ← Requirements, PRDs, feature specs
├─ 02_architecture/   ← System design, data flow, components
├─ 03_decisions/      ← Architecture Decision Records (ADRs), tradeoffs
├─ 04_knowledge/      ← Reusable concepts & explanations
├─ 05_prompts/        ← Reusable LLM prompts & system instructions
├─ 06_agents/         ← Agent roles, rules, memory
├─ 07_diagrams/       ← Mermaid diagrams (one per file)
├─ 08_logs/           ← Append-only logs, session summaries, changelogs
├─ 99_scratch/        ← Drafts, temporary thinking, WIP notes
└─ todos/             ← TODO lists and task tracking

### Reading context
- Before starting work, check `ContextDB/` for relevant notes, decisions, and specs
- Read `ContextDB/README.md` to understand folder structure and conventions
- Check `00_index/` for project maps and entry points
- Check for existing files before creating new ones (prefer appending)

### Writing context
- Route files to the correct taxonomy folder
- Use descriptive filenames — date-prefix when chronology matters
- Always **append** to existing files rather than overwriting, unless explicitly instructed
- Do **not** delete files without explicit user permission
- Create taxonomy folders on first use if they don't exist yet

### Conventions
- Plain Markdown only (`.md`)
- Include a `# Title` heading in every file
- Use relative links to reference other files
- Prefer **small, composable files** over large monoliths

Routing: what your agent does with a request

The instructions include a routing table, so "record this decision" lands somewhere predictable instead of at the end of a chat transcript.

You say	It lands in	Example
"write a spec", "document requirements"	`01_specs/`	checkout-redesign.md
"document the architecture", "explain how X works"	`02_architecture/`	payments.md
"record this decision", "why did we choose X"	`03_decisions/`	2026-02-07-prisma-downgrade.md
"save this knowledge", "document this pattern"	`04_knowledge/`	stripe-webhook-patterns.md
"save this prompt"	`05_prompts/`	code-review-prompt.md
"log this session", "update context"	`08_logs/`	2026-02-07-session-summary.md
"create a todo", "track these tasks"	`todos/`	2026-02-07-refactor-tasks.md

Starter templates

Templates worth copying into your ContextDB. These are conventions to paste, not a feature in the app — consistent structure is what makes a folder cheap for an agent to read.

Spec / Requirement

01_specs/feature-name.md

# Spec: [Feature Name]

## Problem statement
[What problem does this solve?]

## Goals
- [ ] Goal 1
- [ ] Goal 2

## Non-goals
- Non-goal 1

## Constraints
- Constraint 1

## Acceptance criteria
- [ ] Criteria 1
- [ ] Criteria 2

## Related
- [Architecture](../02_architecture/feature-name.md)
- [Decision](../03_decisions/YYYY-MM-DD-decision-name.md)

Architecture

02_architecture/feature-name.md

# Architecture: [Feature Name]

## Overview
[Brief description of what this covers.]

## Requirements
- [Spec](../01_specs/feature-name.md)

## Design
[High-level approach]

## Interfaces
[API contracts, data models, or UI components]

## Rules
- [The constraints an agent must not violate]

## Open questions
- [ ] Question 1

Decision Record (ADR-lite)

03_decisions/YYYY-MM-DD-decision-name.md

# Decision: [Title]

**Date:** YYYY-MM-DD
**Status:** Proposed | Accepted | Superseded

## Context
[What is the situation? What forces are at play?]

## Options considered
1. **Option A** — [Brief description]
   - Pro: ...
   - Con: ...
2. **Option B** — [Brief description]
   - Pro: ...
   - Con: ...

## Decision
[Which option was chosen and why.]

## Consequences
- [What changes as a result?]
- [What do we accept as the cost?]

Session log

08_logs/YYYY-MM-DD-session.md

# YYYY-MM-DD session

## What changed
- [Summary of the work]

## Decisions made
- [Decision] → recorded in [03_decisions/...](../03_decisions/)

## Still open
- [ ] [What the next session should pick up]

Working next to an agent

A few habits that make the context worth keeping.

Write the constraints down, not just the goals — "don't add another payment abstraction" is the sentence an agent can't infer from your code.
End a session by logging what changed and what's still open. That file is the cheapest context you'll ever give the next session.
Keep each file focused on one topic. Small files mean an agent reads what it needs and nothing else.
Link related files with relative Markdown links instead of duplicating context — the link resolves in the preview, so you can follow it too.
Bundle the minimum set of files for the question you're asking, not the whole folder.
Record decisions when you make them. The rationale is what disappears first.

Give your agent something to read.

7-day free trial · Native macOS · Local-first

Download on the Mac App Store