Configuration

Ixchel tools use a unified ~/.ixchel/ directory for global configuration and state, and a per-repo .ixchel/ directory for canonical Markdown artifacts (issues, decisions, sources, etc).

Directory Structure

~/.ixchel/
├── config/                   # Configuration (user-editable TOML)
│   ├── config.toml           # Shared settings
│   └── ixchel.toml           # ixchel settings
│
├── data/                     # Caches & databases (auto-generated)
│
├── state/                    # Runtime metadata (ephemeral)
│   ├── agents/               # Agent registry
│   ├── locks/                # Process locks
│   └── cache/                # Computed caches
│
└── log/                      # Operation logs

Per-repo canonical artifacts live in .ixchel/ at the repository root.

Config Hierarchy

Settings are loaded with this priority (highest first):

1. Environment variables (IXCHEL_*, GITHUB_TOKEN)
2. Global tool config (~/.ixchel/config/<tool>.toml)
3. Global shared config (~/.ixchel/config/config.toml)
4. Project tool config (.ixchel/<tool>.toml)
5. Project shared config (.ixchel/config.toml)
6. Defaults (from code)

Global Config

Shared Settings

~/.ixchel/config/config.toml contains settings used by multiple tools:

[github]
token = "ghp_xxx"  # Or use GITHUB_TOKEN env var

[embedding]
model = "BAAI/bge-small-en-v1.5"
batch_size = 32

[storage]
backend = "helixdb"
path = "data/ixchel" # relative to .ixchel/

Tool-Specific Settings

Each tool has its own config file:

# ~/.ixchel/config/ixchel.toml
[issues]
default_status = "open"

Project Config

Project-local settings live in .ixchel/ at the repo root:

your-project/.ixchel/
├── config.toml           # Project shared config
├── ixchel.toml           # ixchel config (optional)
└── issues/               # Canonical artifacts (Markdown, git-tracked)

Environment Variables

Override any setting via environment variables:

# Override ixchel home directory
export IXCHEL_HOME=~/my-ixchel

# Shared settings
export GITHUB_TOKEN=ghp_xxx
export IXCHEL_EMBEDDING_MODEL=jina-embeddings-v3

Data Locations

Per-repo .ixchel/ directories contain both:

• Canonical Markdown artifacts (.ixchel/**/*.md) that should be committed
• Rebuildable caches (.ixchel/data/, .ixchel/models/) that are gitignored

Why This Structure?

Unlike tools that scatter config across ~/.config/ and data across ~/.cache/, Ixchel uses a single directory. This follows the pattern of:

• Rust: ~/.cargo/, ~/.rustup/
• Node: ~/.npm/, ~/.nvm/
• Ruby: ~/.gem/, ~/.rbenv/

Benefits:

• Single location to manage, backup, or reset
• Clear separation between config (user edits) and data (auto-generated)
• Easy to understand what's safe to delete