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 your AI agent write into your workspace

Point Claude Code, Cursor, Windsurf, or any agent at your workspace. Add the ContextDB snippet to your Claude.md (or .cursorrules, or equivalent config) 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 Edit, Split, or Read mode. Mermaid diagrams and syntax highlighting render automatically in the preview.

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 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_index/        # Workspace overview, README, onboarding
  01_specs/        # Requirements, problem statements, goals
  02_architecture/ # System design, interfaces, data models
  03_decisions/    # ADR-lite decision records
  04_knowledge/    # Summaries, research, domain reference
  05_prompts/      # Prompt patterns, reusable instructions
  06_agents/       # Agent configs, skills, automation
  07_diagrams/     # Mermaid diagrams and visuals
  08_logs/         # Session logs, changelogs, audit trails
  99_scratch/      # Temporary notes, drafts, experiments
  todos/           # Action items, milestones, checklists

00_index/

Workspace overview: README, table of contents, onboarding notes.

Use for the workspace entry point. Keep a README here that summarizes the project and links to key docs.

01_specs/

Requirements, problem statements, goals/non-goals, acceptance criteria.

Use when defining what needs to be built. Each requirement or spec should be a separate file.

02_architecture/

System architecture, interfaces, data models, API contracts.

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

03_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.

04_knowledge/

Curated knowledge: summaries, research, domain reference material.

Use for condensed overviews, research notes, and domain-specific reference. Never overwrite raw notes — always create a new summary.

05_prompts/

Prompt patterns, reusable instructions, agent playbooks.

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

06_agents/

Agent configurations, skills, tool definitions, automation scripts.

Use for agent-specific config files, custom skills, and automation playbooks.

07_diagrams/

Mermaid diagrams and visual explanations (can be referenced).

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

08_logs/

Session logs, changelogs, audit trails.

Use for tracking what happened over time — session transcripts, change history, or progress logs.

99_scratch/

Temporary notes, drafts, experiments. Safe to delete.

Use for quick captures, brainstorming, or anything that hasn't been categorized yet. Process or delete regularly.

todos/

Action items, milestones, checklists, backlog slices.

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

Naming conventions

• Use snake_case for folders: 01_specs/, 03_decisions/
• Use kebab-case for files: 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 (or .cursorrules, or equivalent) to instruct your AI agent 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](../02_architecture/onboarding-spec.md)`
- Prefer linking instead of duplicating context.

### Taxonomy (preferred)
ContextDB/
  00_index/
  01_specs/
  02_architecture/
  03_decisions/
  04_knowledge/
  05_prompts/
  06_agents/
  07_diagrams/
  08_logs/
  99_scratch/
  todos/

### 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 or spec → create a file in `01_specs/`
- Architecture or implementation plan → create/update in `02_architecture/`
- A decision or tradeoff → create an ADR-lite in `03_decisions/`
- Knowledge or research → write to `04_knowledge/`
- Reusable prompts → store in `05_prompts/`
- Agent configs → store in `06_agents/`
- Diagrams → create in `07_diagrams/`
- Action items → update a TODO file in `todos/`

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.

Spec / Requirement

01_specs/feature-name.md

Spec / Requirement

# 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-arch.md)
- [Decision](../03_decisions/YYYY-MM-DD-decision-name.md)

Architecture

02_architecture/feature-name-arch.md

Architecture

# 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]

## Data model
[Key entities and relationships]

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

## Open questions
- [ ] Question 1

Decision Record (ADR-lite)

03_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
- [Spec](../01_specs/related.md)
- [Architecture](../02_architecture/related-arch.md)

TODO List

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]

Knowledge Summary

04_knowledge/topic-summary.md

Knowledge Summary

# Knowledge: [Topic]

## Summary
[Concise overview of the topic.]

## Key points
- Point 1
- Point 2

## Decisions referenced
- [Decision](../03_decisions/YYYY-MM-DD-decision.md)

## Related specs
- [Spec](../01_specs/feature-spec.md)

## Open items
- Item 1

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 05_prompts/ and reference them by path
• Summarize periodically into 04_knowledge/ so agents have a quick overview without reading every file