Skip to main content
Colin projects are configured through colin.toml, a TOML file in your project root. This file defines project metadata, directory paths, output destinations, LLM settings, and MCP server connections.

​
Project Settings

The [project] section contains core project configuration:
colin.toml
[project]
name = "my-context"
model-path = "models"
output-path = "output"
SettingDescriptionDefault
nameProject name for displayDirectory name
model-pathDirectory containing source documentsmodels
output-pathDirectory for compiled output (see Output Targets)output

​
Directory Paths

Paths can be relative to the location of colin.toml or absolute: 
[project]
name = "documentation"
model-path = "src/context"
output-path = "dist"
With this configuration, Colin reads from src/context/ and writes to dist/. Absolute paths are also supported: 
[project]
name = "documentation"
output-path = "/tmp/colin-output"
When using absolute paths, they are preserved as-is and not resolved relative to the project root.

​
Output Targets

Output targets control where Colin writes compiled files. The simple output-path setting works for most projects, but when you need more control over output behavior, use the [project.output] section.

​
Target Types

Colin supports three target types, each suited to different use cases. Local targets write to a directory you specify. This is the default behavior and equivalent to using output-path directly. The entire output directory is managed as a unit, with a single manifest at the root tracking all files.
colin.toml
[project.output]
target = "local"
path = "dist"
Skill targets are designed for projects that generate multiple independent skill sets. Each first-level subdirectory receives its own manifest file, enabling granular tracking and cleanup. When your project outputs files to stripe/payments.md and github/issues.md, Colin writes separate manifests to stripe/.colin-manifest.json and github/.colin-manifest.json.
colin.toml
[project.output]
target = "skill"
path = "output/skills"
Claude skill targets write directly to Claude Code’s skills directory. Skills placed here become available to Claude Code sessions automatically. The scope parameter determines whether skills are user-wide or project-specific.
colin.toml
[project.output]
target = "claude-skill"
scope = "user"
With scope = "user", Colin writes to ~/.claude/skills/. This makes skills available in all Claude Code sessions on your machine. With scope = "project", Colin writes to .claude/skills/ relative to the project. Colin searches upward from the project root to find an existing .claude directory; if none exists, it creates one in the project root. Project-scoped skills are available only when Claude Code runs from within that project.
colin.toml
[project.output]
target = "claude-skill"
scope = "project"
You can override the default location with an explicit path, which takes precedence over the scope-based location:
colin.toml
[project.output]
target = "claude-skill"
path = "/custom/skills/location"

​
Manifest Ownership

Each target type determines how manifests track file ownership. Manifests enable Colin to clean up stale files without affecting unrelated content in the output directory. Local targets use a single manifest at the output root. All files in the directory are considered managed by Colin. Skill targets and Claude skill targets use per-subdirectory manifests. Each first-level directory (like stripe/ or github/) gets its own manifest that tracks only files within that directory. This allows different projects or compilation runs to write to sibling directories without interfering with each other.

​
Compatibility

The simple output-path configuration remains fully supported. When you use output-path, Colin treats it as a local target with that path:
colin.toml
[project]
output-path = "output"
This is equivalent to:
colin.toml
[project.output]
target = "local"
path = "output"
Use output-path for straightforward local output. Switch to [project.output] when you need skill manifests or Claude Code integration.

​
LLM Provider

Configure the default LLM model using [[providers.llm]]:
colin.toml
[[providers.llm]]
model = "anthropic:claude-haiku-4-5"
Model identifiers follow the format provider:model-name. Currently supported providers:
ProviderExample Models
anthropicclaude-sonnet-4-5, claude-haiku-4-5
openaigpt-4o, gpt-4o-mini
Individual LLM blocks can override the project default: 
{% llm model="anthropic:claude-sonnet-4-5" %}
Complex analysis requiring a more capable model...
{% endllm %}
If no model is configured, Colin falls back to COLIN_DEFAULT_LLM_MODEL environment variable, then to anthropic:claude-sonnet-4-5.

​
MCP Servers

MCP servers are configured under [[providers.mcp]]. Each entry requires a name that becomes accessible in templates as colin.mcp.<name>. See Providers for usage documentation.

​
Stdio Servers

Local process servers communicate via stdin/stdout:
colin.toml
[[providers.mcp]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]

[[providers.mcp]]
name = "linear"
command = "npx"
args = ["-y", "@linear/mcp-server"]

[[providers.mcp]]
name = "filesystem"
command = "npx"
args = ["@anthropic/mcp-server-filesystem", "/path/to/data"]
FieldDescription
commandExecutable to run
argsCommand-line arguments as an array
envEnvironment variables as a table
Optional scheme-suffix overrides the URI scheme suffix (defaults to name). Templates still use the name, but ref URIs use mcp.<scheme-suffix>://....

​
Environment Variables

Pass environment variables to server processes:
colin.toml
[[providers.mcp]]
name = "postgres"
command = "npx"
args = ["@anthropic/mcp-server-postgres"]
env = { DATABASE_URL = "postgres://user:pass@localhost/db" }
Reference shell environment variables with ${VAR} syntax: 
[[providers.mcp]]
name = "postgres"
command = "npx"
args = ["@anthropic/mcp-server-postgres"]
env = { DATABASE_URL = "${DATABASE_URL}" }
Colin substitutes the value from your environment when starting the server.

​
Remote Servers

HTTP and SSE servers connect over the network:
colin.toml
[[providers.mcp]]
name = "remote-api"
url = "https://api.example.com/mcp"
For servers requiring authentication headers:
colin.toml
[[providers.mcp]]
name = "authenticated"
url = "https://api.example.com/mcp"
headers = { Authorization = "Bearer ${API_TOKEN}" }

​
Using MCP Resources

Reference configured servers in your documents:
models/sources/projects.md
---
name: Project Data
---

{{ colin.mcp.linear.resource('projects?team=engineering') }}
The server name comes from the configured name, and the argument is the resource URI, which varies by server.

​
Environment Variables

Colin supports environment variables for global settings:
Environment VariableDescriptionDefault
COLIN_DEFAULT_LLM_MODELFallback LLM model when not configured in projectanthropic:claude-sonnet-4-5
COLIN_FERNET_KEYEncryption key for OAuth token storageNone (unencrypted)
The precedence order for LLM models is: [[providers.llm]] model → COLIN_DEFAULT_LLM_MODEL → built-in default.

​
OAuth Token Encryption

OAuth tokens for providers like Linear and Notion are stored at ~/.colin/mcp-oauth/. By default, tokens are stored unencrypted. To encrypt stored tokens, set COLIN_FERNET_KEY to a Fernet encryption key: 
# Generate a key
python -c 'from cryptography.fernet import Fernet; print(Fernet.generate_key().decode())'

# Set it in your environment
export COLIN_FERNET_KEY="your-generated-key-here"
When set, Colin encrypts tokens before writing and decrypts when reading. If you change or remove the key, existing tokens become unreadable and you’ll need to re-authenticate.

​
Environment Variable Substitution

Colin substitutes ${VAR} patterns anywhere in colin.toml:
colin.toml
[[providers.llm]]
model = "${LLM_MODEL:-anthropic:claude-haiku-4-5}"

[[providers.mcp]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }
Default values use shell syntax: ${VAR:-default}. If LLM_MODEL is unset, Colin uses anthropic:claude-haiku-4-5. Unset variables without defaults become empty strings. This is useful for optional configuration but can cause errors if required values are missing—Colin won’t warn about unset variables at parse time.

​
Complete Example

A full configuration demonstrating all options:
colin.toml
[project]
name = "engineering-context"
model-path = "context"

[project.output]
target = "claude-skill"
scope = "user"

[[providers.llm]]
model = "anthropic:claude-sonnet-4-5"

[[providers.mcp]]
name = "github"
command = "uvx"
args = ["mcp-server-github"]
env = { GITHUB_TOKEN = "${GITHUB_TOKEN}" }

[[providers.mcp]]
name = "linear"
command = "npx"
args = ["-y", "@linear/mcp-server"]
env = { LINEAR_API_KEY = "${LINEAR_API_KEY}" }

[[providers.mcp]]
name = "warehouse"
command = "npx"
args = ["@anthropic/mcp-server-postgres"]
env = { DATABASE_URL = "${DATA_WAREHOUSE_URL}" }

[[providers.mcp]]
name = "internal-api"
url = "https://internal.company.com/mcp"
headers = { Authorization = "Bearer ${INTERNAL_API_TOKEN}" }
This configuration reads source documents from context/, compiles them using Claude Sonnet for any LLM operations, and writes the results directly to your user-level Claude Code skills directory. The compiled skills become immediately available in all your Claude Code sessions. Four MCP servers provide access to GitHub, Linear, a Postgres data warehouse, and an internal API.