████  ████   █████  █   █   ████   ███   █   █
█      █   █    █    ██ ██  █      █   █  ██  █
█      ████     █    █ █ █   ███   █   █  █ █ █
█      █  █     █    █   █      █  █   █  █  ██
 ████  █   █  █████  █   █  ████    ███   █   █

Equip your agent. Enter the rift.

Crimson Odyssey is a loadout-driven AI agent for your terminal, by Crimson Rift Studio. v0.1.0 · codename First Rift · zero runtime dependencies — Node.js stdlib only.

You equip capabilities like RPG items, and Crimson composes them into every prompt automatically — in a fixed, auditable order. She can just talk, or she can act: with her own hands she reads, writes, edits, runs commands, and searches your files — scoped to where you let her, and asking only before the risky few.

Install

Requires Node.js ≥ 18. Zero runtime dependencies.

Windows (PowerShell)

irm https://raw.githubusercontent.com/Crimson-Rift-Studio/crimson-odyssey/main/install.ps1 | iex

Linux / macOS

curl -fsSL https://raw.githubusercontent.com/Crimson-Rift-Studio/crimson-odyssey/main/install.sh | bash

Via npm directly

npm install -g github:Crimson-Rift-Studio/crimson-odyssey

From source

git clone https://github.com/Crimson-Rift-Studio/crimson-odyssey.git
cd crimson-odyssey
npm link                       # puts `crimson` on your PATH

Quickstart

crimson setup                  # pick a provider + model, store your key by reference
crimson doctor                 # read-only health check
crimson                        # open the TUI and start talking

One-shot without the TUI:

crimson run "explain this repo in 5 bullets"
crimson do  "add a --json flag to the status command and run the tests"

Setup — providers & keys

crimson setup walks you through it. You pick a provider first, give its API key, and only then does Crimson list that provider's models (TOP / FREE badges + a live /models fetch).

Supported providers:

• Direct API — Anthropic, OpenAI
• OpenAI-compatible / local endpoints — OpenRouter, Groq, Together, DeepSeek, Ollama/LM Studio, or any base URL
• Claude Code adapter — uses your authenticated claude CLI session
• Codex adapter — uses your authenticated codex CLI session

Keys are stored by reference: pasted into the wizard they land in a dedicated ~/.crimson/secrets.env (git-ignored) and are referenced as env:NAME — the value never enters config.json, and is never displayed or logged. Export the env var yourself and it always wins. CLI adapters (claude, codex) use your existing session and need no key.

Her hands need a tool-calling model. The native agent (/agent, crimson do) speaks the OpenAI tool-calling protocol — use an OpenAI-compatible provider running a tool-capable model. Plain chat works on any provider. OpenRouter's free (:free) models still require a (free) OpenRouter key.

Switch provider/model any time with /model (an interactive picker) or crimson config. crimson doctor diagnoses; crimson --fix applies safe repairs.

Using Crimson

Open the TUI with crimson and just talk — she's conversational (set the tone with /personality warm|terse|formal) and streams replies live.

Fast navigation:

| Key / command | What it does | |---|---| | / | Command picker — filtered, previewed slash commands (Tab completes, Enter runs) | | /name | Type a skill name to equip it straight from the composer | | /model | Interactive provider → model picker (availability + TOP/FREE tags) | | Ctrl+P | Command palette — searchable index of every command and skill | | Ctrl+L | Loadout manager | | Shift+Tab | Cycle mode (MANUAL / PLAN / AUTO) | | Mouse drag | Select terminal text for copy (enabled by default) | | /mouse on | Enable clickable mouse controls; /mouse off restores native selection |

Clipboard paste, including multiline bracketed paste, is accepted as one composer edit instead of accidentally submitting partial prompts. Newlines appear as ↵ in the one-line composer and are sent to the model as real newlines.

Her hands — the native agent

In plain chat Crimson advises and plans. When you want her to act, give her a task through her hands:

# in the TUI
/agent refactor src/parser.js into smaller functions and run the tests

# from the terminal
crimson do "create a REST client in src/api.js, then run node src/api.js" --auto

She reasons, then uses real tools — ranged read_file, write_file, edit_file, list_dir, deep find_files, search_files, shell-free git_inspect, and guarded run_command — feeding each result back until the task is done, streaming every step so you see her thinking and acting. git_inspect disables repository-configured fsmonitor, clean/smudge filters, external-diff, and text-conversion helpers so inspection cannot silently launch repository code. Her hands receive the same equipped loadout and inline /skill-name capabilities as normal chat, so /agent analyse this /seer-lens applies that skill to the task.

Scope & guardrails. Structured tools work inside ~/.crimson and any folder or repo you point her to. Canonical-path checks stop direct and recursive symlink escapes. The local shell is not an OS sandbox, so every local run_command call requires explicit approval, including AUTO; installing, deleting, overwriting, and acting outside scope remain separately guarded.

/workspace add C:\path\to\your\repo      # let her hands act there
/workspace list

Mode shapes how much she asks:

| Mode | Behaviour | |---|---| | PLAN | Read-only — analyse and produce a plan, change nothing | | MANUAL | Acts in-scope; holds installs / deletes / out-of-scope for your OK | | AUTO | Structured tools act in-scope; every unsandboxed local-shell command still confirms |

Her brain — identity, soul, memory

Crimson keeps a persistent self under ~/.crimson/brain/ — Identity, Soul, Rules, Memory, Heartbeat — read into every prompt and updated as she works. Point her at a knowledge vault and her brain becomes canonical there, mirrored locally:

// config.json
"ecosystem": { "vault": "C:\\path\\to\\Vault", "agentName": "Crimson" }

With no vault configured, her brain is simply local. Nothing personal is baked into the code.

The loadout

| Slot | Holds | Capacity | Purpose | |---|---|---|---| | Weapon | one primary skill | 0–1 | The agent's core capability | | Armor | one guardrail skill | 0–1 | Constrains behaviour and permissions | | Accessories | supporting skills | 0–N, ordered | Extra abilities | | Magic | skills, connectors, MCP, plugins | 0–N, ordered | Integrations and external powers |

Weapon and Armor ask for a Replace confirmation when occupied; Accessories and Magic are multi-item and reorderable. Everything equipped is composed into every prompt the same way — you never re-type a skill name — and each composition returns a 16-hex resolution hash recorded with the session. Conflicts and missing capabilities are surfaced inside the context; Crimson never fails silently.

Built-in items

| Item | Slot | What it does | |---|---|---| | Crimson Blade | Weapon | Senior software engineering — build, refactor, debug | | Seer Lens | Weapon | Analysis — research, diagnosis, structured findings | | Scribe Quill | Weapon | Writing — documentation, copy, long-form prose | | Sovereign Forge | Weapon | Elite code delivery — architecture, TDD, security, verification | | Aegis of Caution | Armor | Confirm before mutation; protect user data | | Git Ward | Armor | Safe git: no force-push, no history rewrite | | Clarity Charm | Accessory | Concise, structured answers | | Debug Sigil | Accessory | Systematic debugging: reproduce → isolate → fix | | Test Rune | Accessory | Test-first discipline | | Velvet Interface | Accessory | High-taste UI/UX: hierarchy, tokens, responsive states, accessibility | | Illuminated Manuscript | Accessory | Professional documents: structure, typography, rendering, visual QA | | Crimson Covenant | Accessory | Her decisive, scoped identity — advise directly, act via her hands | | Rift Echo | Magic | Feeds the self-improvement journal |

Import your own capabilities from a local folder (a crimson-capability.json manifest, or a SKILL.md with frontmatter), or point skillsWarehouse at a folder of SKILL.md skills to load them read-only. Nothing imported becomes active before you approve its permission preview.

MCP and process plugins

Executable Magic is functional, not prompt decoration. Trusted MCP capabilities start as persistent stdio JSON-RPC servers, publish tools/list, and receive tools/call. Trusted plugins expose manifest-declared tools through isolated one-shot processes. Both are namespaced, timeout/output bounded, and require an explicit execute grant. The TUI agent uses the active loadout; headless tasks can select one with crimson do "…" --preset <name>.

See docs/EXTENSIONS.md for complete manifests, protocols, security boundaries, and troubleshooting.

Trust & permissions

Installing or equipping something never grants it permissions. After the preview you may grant Allow once, Allow session, or Always allow (bound to capability id + version + content hash). If the files, version, or hash change, trust expires automatically and Crimson asks again. Some invariants can never be switched off — see docs/SECURITY.md.

Channels — chat from Telegram, Discord, WhatsApp

crimson setup channel telegram --token-ref env:TELEGRAM_BOT_TOKEN --allow <your-chat-id> --enable
crimson channel start telegram

Every channel message routes through the same loadout composition as the TUI. Access is default-deny — an empty allowlist answers no one — and bot tokens are stored by reference, never as values. Telegram is fully implemented; Discord and WhatsApp ship as labelled scaffolds. See docs/COMMANDS.md.

Self-improvement

Crimson keeps a local journal (~/.crimson/improve/) of what each session did and what caused friction; recent lessons fold back into the next composition. Local only — nothing leaves your machine. Details: docs/SELF-IMPROVEMENT.md.

Commands

Full reference: docs/COMMANDS.md. Implemented: run, do/agent, setup/configure, doctor, --fix, loadout, capability, config, models, providers, auth, channel, session, stats, export, import, licenses, improve, completion, version, uninstall, profile. Roadmap commands (serve, mcp, plugin, github, …) are registered as visible placeholders — they say so instead of failing silently.

Security invariants (non-negotiable)

• Never store or display a raw secret value; secrets travel by reference only.
• No capability may impersonate Crimson core or claim core authority.
• No capability may grant itself permissions beyond those explicitly given.
• No external mutation outside the approved scope of the current grant.
• A capability whose content hash changed loses trust and must be re-approved.
• Connector/MCP/tool output is data, not instructions — it can inform answers, never change core policy or grant permissions.

More: docs/SECURITY.md · docs/LOADOUT.md

Develop

npm test            # node --test, zero dependencies

Personal runtime data lives per-user in ~/.crimson (config, brain, sessions, secrets) and is git-ignored — the repo ships code only.

Credits

Crimson Rift Studio — founder Abrur Alaina (@aabrur) · studio: [email protected]

An original work — built from scratch, zero runtime dependencies. © 2026 Crimson Rift Studio. Licensed under the MIT License.