How to use ContextLoom

From install to organized workspace in five minutes.

Get started in 5 steps

Install ContextLoom

Download ContextLoom from the Mac App Store or our website. Open it and grant file access permissions when prompted.

Create or open a workspace

A workspace is any folder on your Mac. Create a new one or open an existing project directory. ContextLoom will index its contents instantly.

Let Claude Code write into your workspace

Point Claude Code (or Cursor, or any agent) at your workspace. Add the ContextDB snippet to your Claude.md so the agent knows where to write. Files appear in ContextLoom as they're created.

Browse, edit, and preview

Use the sidebar to navigate files. Open any Markdown file in split view to see the editor and rendered preview side by side. Mermaid diagrams render automatically.

Export Context Bundles

Select the files you need for your next prompt. ContextLoom exports them as a single, token-optimized context bundle you can paste directly into Claude or any LLM.

Recommended ContextDB taxonomy

Organize your workspace with this folder structure. Each folder has a clear purpose, making it easy for both humans and LLMs to find what they need.

Folder structure

ContextDB/
  00-inbox/          # Raw capture: notes, dumps, imports
  10-requirements/   # Problem statements, goals, constraints
  20-specs/          # Engineering specs, architecture, interfaces
  30-decisions/      # ADR-lite decision records
  40-todos/          # Action items, milestones, checklists
  50-summaries/      # Curated summaries of folders/projects
  60-diagrams/       # Mermaid diagrams and visual explanations
  70-prompts/        # Prompt patterns, reusable instructions

00-inbox/

Raw capture: notes, dumps, imports. Minimal structure.

Use for quick notes, meeting dumps, or anything that hasn't been categorized yet. Process regularly.

10-requirements/

Problem statements, goals/non-goals, constraints, acceptance criteria.

Use when defining what needs to be built. Each requirement should be a separate file with clear acceptance criteria.

20-specs/

Engineering specs, architecture, interfaces, data models, flows.

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

30-decisions/

ADR-lite decision records (tradeoffs, rationale, consequences).

Use when a significant technical or product decision is made. Record the context, options considered, and rationale.

40-todos/

Action items, milestones, checklists, backlog slices.

Use for tracking work. Keep TODO files focused — one per feature or sprint.

50-summaries/

Curated summaries of folders/projects/time windows.

Use to condense raw notes and specs into overviews. Never overwrite raw notes — always create a new summary.

60-diagrams/

Mermaid diagrams and visual explanations (can be referenced).

Use for flowcharts, sequence diagrams, architecture visuals. ContextLoom renders these in the preview pane.

70-prompts/

Prompt patterns, reusable instructions, agent playbooks.

Use to store proven prompts you reuse. Reference them in context bundles.

Naming conventions

• Use kebab-case: onboarding-flow.md, auth-architecture.md
• Prefix decisions with date or ADR number: 2026-02-07-adr-auth0-vs-custom-sso.md or ADR-0003-workspace-file-watcher.md
• Keep templates consistent so LLMs can scan quickly
• Use .md extension for all files (UTF-8 only)

Claude.md snippet

Paste this into your project's Claude.md file to instruct Claude Code how to write into your ContextDB workspace. This ensures consistent file organization and LLM-friendly conventions.

Claude.md — paste this into your project

## ContextLoom + ContextDB Conventions (LLM Instructions)

This workspace is a local-first context repository. The filesystem is the source of truth.

### Where to write
- Prefer creating/updating Markdown files under: `/ContextDB/`
- Use the taxonomy folders below. Create subfolders if helpful.
- Keep files small and modular. Add new files rather than rewriting large ones.

### Safety rules
- Do not reformat or rewrite existing files unless explicitly asked.
- Preserve content and intent. Prefer additive changes (append sections, add new docs).
- Use UTF-8 `.md` only. No proprietary formats.

### Linking
- Use relative Markdown links when referencing other files:
  - `[Onboarding Spec](../20-specs/onboarding-spec.md)`
- Prefer linking instead of duplicating context.

### Taxonomy (preferred)
ContextDB/
  00-inbox/
  10-requirements/
  20-specs/
  30-decisions/
  40-todos/
  50-summaries/
  60-diagrams/
  70-prompts/

### Context Bundles (for prompts)
When asked to provide context for a prompt, output as:

```
# Context Bundle

## /relative/path/to/file.md
<file contents>
```

Include only the minimum set of files needed to answer (token-optimized).

### Default behaviors
- New requirement → create a file in `10-requirements/`
- Implementation plan/spec → create/update in `20-specs/`
- A decision or tradeoff → create an ADR-lite in `30-decisions/`
- Action items → update a TODO file in `40-todos/`
- Summaries → write to `50-summaries/` (do not overwrite raw notes)

File templates for LLM-friendly structure

Use these templates when creating new files. Consistent structure lets LLMs scan faster, waste fewer tokens, and produce more deterministic results.

Requirement

10-requirements/feature-name.md

Requirement

# Requirement: [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
- [Spec](../20-specs/feature-name-spec.md)
- [Decision](../30-decisions/YYYY-MM-DD-decision-name.md)

Spec

20-specs/feature-name-spec.md

Spec

# Spec: [Feature Name]

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

## Requirements
- [Requirement](../10-requirements/feature-name.md)

## Architecture
[High-level approach]

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

## Data model
[Key entities and relationships]

## Flow
[Step-by-step flow or link to diagram]
- [Flow diagram](../60-diagrams/feature-name-flow.md)

## Open questions
- [ ] Question 1

Decision Record (ADR-lite)

30-decisions/YYYY-MM-DD-decision-name.md

Decision Record (ADR-lite)

# 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 of this decision?]
- [What are the risks?]

## Related
- [Requirement](../10-requirements/related.md)
- [Spec](../20-specs/related-spec.md)

TODO List

40-todos/feature-or-sprint-name.md

TODO List

# TODOs: [Feature / Sprint Name]

**Last updated:** YYYY-MM-DD

## In progress
- [ ] Task 1 — [Owner] — [Notes]

## Up next
- [ ] Task 2
- [ ] Task 3

## Done
- [x] Completed task

## Blocked
- [ ] Blocked task — Reason: [why]

Weekly Summary

50-summaries/YYYY-WXX-summary.md

Weekly Summary

# Summary: Week of YYYY-MM-DD

## Highlights
- Highlight 1
- Highlight 2

## Decisions made
- [Decision](../30-decisions/YYYY-MM-DD-decision.md)

## Key changes
- [Spec updated](../20-specs/feature-spec.md)

## Open items
- Item 1

## Next week
- Priority 1
- Priority 2

Skills setup for agents

Structure your workspace so LLMs can quickly find what they need. When files follow a consistent taxonomy and template, agents spend fewer tokens scanning and produce more accurate results.

Benefits

Faster traversal: agents jump directly to the right folder instead of scanning everything
Less token waste: structured files mean shorter prompts with more signal
More deterministic prompting: consistent templates produce consistent outputs
Easy context bundles: grab exactly the files needed for a prompt

Tips for structuring files

• Keep each file focused on one topic — LLMs work better with small, modular files
• Use the templates above so every file has a predictable structure
• Link related files with relative Markdown links instead of duplicating content
• Store reusable prompts in 70-prompts/ and reference them by path
• Summarize periodically into 50-summaries/ so agents have a quick overview without reading every file