Skip to main content
A Colin project is a directory containing a colin.toml configuration file and a models/ directory with your source documents. When you compile, Colin reads from models/ and writes to output/.

​
Project Structure

A typical project looks like this: 
my-project/
├── colin.toml          # Project configuration
├── models/             # Source documents
│   ├── company.md
│   ├── products/
│   │   ├── widget.md
│   │   └── gadget.md
│   └── team/
│       └── overview.md
└── output/              # Compiled output (generated)
    ├── manifest.json
    ├── company.md
    ├── products/
    │   ├── widget.md
    │   └── gadget.md
    └── team/
        └── overview.md
Colin discovers all .md files in models/ recursively, compiles them in dependency order, and mirrors the directory structure into output/.

​
Configuration

The colin.toml file defines project settings:
colin.toml
[project]
name = "my-context"
model-path = "models"

[project.output]
path = "output"
SettingDescriptionDefault
nameProject name for displayDirectory name
model-pathSource documents directorymodels
[project.output] pathCompiled output directoryoutput
For advanced output configuration including Claude Code integration, see Output Targets.

​
LLM Provider

Configure the default LLM model:
colin.toml
[[providers.llm]]
model = "anthropic:claude-haiku-4-5"
See Configuration for details on model identifiers and overrides.

​
MCP Servers

Configure MCP servers for external data sources:
colin.toml
[project]
name = "my-context"

[[providers.mcp]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]

[[providers.mcp]]
name = "linear"
command = "npx"
args = ["@linear/mcp-server"]
Reference MCP resources in documents with colin.mcp.<server>.resource(): 
{{ colin.mcp.github.resource('repo://owner/repo/readme') }}

​
Initializing Projects

Create a new project with colin init: 
mkdir my-context && cd my-context
colin init
This creates colin.toml and an empty models/ directory. Add documents to models/ and run colin run to compile. For an existing directory: 
cd existing-project
colin init
Colin creates the configuration file using the directory name as the project name.

​
Organizing Documents

Use subdirectories to group related documents. The directory structure becomes part of each document’s URI: 
models/
├── context/
│   ├── company.md          → URI: context/company
│   └── industry.md         → URI: context/industry
├── products/
│   ├── overview.md         → URI: products/overview
│   └── features/
│       ├── core.md         → URI: products/features/core
│       └── enterprise.md   → URI: products/features/enterprise
└── skills/
    └── support-agent.md    → URI: skills/support-agent
Reference documents using their full URI path:
models/skills/support-agent.md
---
name: Support Agent Context
---

# Company Background

{{ ref('context/company').content }}

# Product Knowledge

{{ ref('products/overview').content }}
{{ ref('products/features/core').content }}

​
Naming Conventions

Choose clear, descriptive names that indicate document purpose: Source documents contain raw or lightly processed information:
  • sources/customer-calls.md
  • sources/linear-projects.md
Context documents synthesize information from multiple sources:
  • context/project-health.md
  • context/customer-sentiment.md
Output documents produce final artifacts like skills or prompts:
  • skills/project-status.md
  • prompts/support-agent.md
This convention makes dependency flow visible: sources feed context, context feeds outputs.

​
The Output Directory

The output/ directory contains all compiled outputs: 
output/
├── manifest.json       # Compilation metadata and cache
├── company.md          # Compiled documents mirror
├── products/           # source structure
│   └── widget.md
└── ...
manifest.json tracks compilation state: document hashes, dependency edges, LLM call cache, and timestamps. Colin uses this to determine what needs recompilation. Compiled documents are plain Markdown with all Jinja templating resolved and LLM outputs substituted. You can read them directly or serve them to other systems.

​
Cleaning Up

Remove all compiled outputs with: 
colin clean
This deletes the entire output/ directory. The next colin run performs a full recompilation.

​
Finding the Project

Colin searches for colin.toml starting from the current directory and walking up to parent directories. This lets you run commands from any subdirectory: 
cd my-project/models/products
colin run  # Finds colin.toml in my-project/
If no colin.toml exists in the directory tree, Colin uses sensible defaults: models/ for source, output/ for output, and the current directory name as the project name.