Orichum

Pronounced: OR-ih-kum, following orichalcum.

Run Claude Code with the models, accounts, project tools, memory, and
specialist agents that fit each project.

Orichum is an independent harness for Claude Code. You continue working inside
Claude Code while Orichum prepares the right model stack, provider account,
project context, and optional tools for the directory you launched from.

Once setup is complete, daily use is simply:

cd ~/projects/my-app
orichum

What Orichum does

• Runs GPT, Claude, Google, Kimi, and other configured models inside the
  familiar Claude Code interface.
• Lets you choose models and named provider accounts while handling safe
  same-family account recovery automatically.
• Loads the right GitHub identity, project tools, memory, and code graph from
  the directory where you start it.
• Keeps concurrent and resumed sessions isolated, while the controller chooses
  relevant context and specialist agents for each task.

You do not need to understand the routing architecture before using Orichum.
Start with one provider and one project; add the other capabilities only when
you need them.

Install

Orichum supports macOS, Linux with a systemd user manager, and WSL2 with
systemd enabled.

git clone https://github.com/orichum/orichum.git
cd orichum
./install.sh

The installer prepares the complete local runtime. Without a provider account,
it completes safely in pending-provider-login state and prints one next
command:

orichum setup

That resumable setup asks for the provider, account name, and projects folder
(default ~/projects). It registers the first account as Primary in Orichum's
internal shared group, creates a compatible recommended model stack, maps the
projects folder, reconciles services, and runs the final health check. Orichum
installs its runtime and all user-managed state under ~/.orichum;
the checkout remains source code only, so editing configuration never dirties
the repository and moving the checkout does not break the installed command.
Later ./install.sh runs quickly when everything is already verified and
healthy. Use ./install.sh --upgrade when you want Orichum to refresh managed
tools within its release constraints and run their complete probes; the full
doctor check follows once a provider route is available. See
Installation and upgrades for details, locations, port
handling, and uninstall options.

Check the installed Orichum release with orichum --version. See the
Changelog for release history and current release-candidate
limitations.

To remove the Orichum runtime while keeping accounts, sessions, project
configuration, and LeanCTX project knowledge for a later reinstall:

./install.sh --uninstall

Use ./install.sh --uninstall --purge only when you also want to permanently
remove Orichum's saved configuration and data.

Your first Orichum session

Run the guided setup after installation:

orichum setup

Setup asks only for provider, account name, and projects folder. It hides
credential filenames, account groups, priorities, and the internal distinction
between the Codex login type and the OpenAI provider adapter. If setup is
interrupted, run the same command again; completed phases are shown as already
configured and are not repeated. Use orichum setup --verbose only when you
need live technical diagnostics; normal setup remains concise.

When setup reports readiness, enter a repository below the configured parent
and launch:

cd ~/projects/my-app
orichum

Orichum resolves the project, prepares an isolated session with the selected
model, account, and relevant tools, then opens Claude Code. From this point,
work normally; the controller decides when project context or a configured
specialist is useful.

The Orichum status line keeps the active model, named account, route state,
context usage, and available provider limits visible. See
Status line.

If launch fails, start with:

orichum doctor

For ongoing changes, use one guided command from the project you want to
change:

orichum configure

It adds accounts, configures a same-provider backup, discovers live models,
assigns models by work type or individual role, previews the complete effect,
and applies it to new sessions. Use orichum configure --project ROOT when you
are administering another configured project. The low-level provider, stack,
and context commands remain available under the guided Advanced area and for
automation.

Daily use

The complete command map is in the CLI reference.

Add capabilities when you need them

• More accounts: use orichum configure to add a named account or an
  explicit same-provider backup without entering pools or priorities. See
  Multi-account routing.
• More model families: use orichum configure to authenticate another
  provider and choose its live models for controller or specialist work. See
  Model stacks.
• Resumes and family changes: resume a frozen session or fork it with a
  bounded handoff onto another stack. See Sessions.
• Memory and code intelligence: LeanCTX recalls durable decisions, reads
  live source, and answers structural or impact questions. See
  Memory and code graph.
• Live source context: LeanCTX gives the controller compact reads, search,
  trees, lossless expansion, approved text patches, and compressed output from
  arbitrary finite CLIs. Specialists reuse the same jailed context engine
  instead of falling back to raw repository reads. A shared LeanCTX wire proxy
  also trims growing conversation history before each request reaches the
  provider.
  See LeanCTX.
• Plugins: declare and synchronize optional Claude Code plugins through
  Orichum. See Plugins.
• Jira: configure private Jira credentials on a project root. Orichum loads
  mcp-atlassian only for sessions below that root. See
  MCP integrations.
• Specialist agents: let the controller delegate bounded exploration,
  review, architecture, or implementation work while keeping one writer. See
  Subagents.

How Orichum fits together

flowchart LR
    P["Project directory"] --> O["Orichum"]
    O --> S["Isolated Claude Code session"]
    M["Selected account and model"] -. "frozen route" .-> S
    S --> L["LeanCTX context and knowledge"]
    S --> W["Shared LeanCTX wire optimization"]
    S -. "only for a bound project" .-> D["mcp-atlassian"]

The directory where you run orichum selects the project configuration.
Orichum opens a private session using the chosen model and account, then makes
only the relevant project context available. You do not select a tool profile
or manually route each request.

Read Architecture for service ownership, security
boundaries, session isolation, and the internal request path.

If something is wrong

Run the bounded health check first:

orichum doctor

Then inspect the part of the setup involved:

orichum config paths
orichum provider accounts
orichum stack list
orichum context list
orichum sessions
orichum leanctx stats

The Troubleshooting guide covers unavailable routes,
connection failures, GitHub identity, missing MCPs, LeanCTX activity,
historical session contracts, and installer port conflicts.

Documentation

Built with

Runs on

• Claude Code — the interactive
  coding host.

Integrates

• Claudex — translates Claude Code requests for
  the selected model.
• CLIProxyAPI — provides
  provider authentication and model access.
• LeanCTX — provides compact live file,
  tree, search, graph, callgraph, and impact context.
• mcp-atlassian — provides
  project-bound Jira tools from each project's private credentials.

Orichum is an independent project. It is not affiliated with or endorsed by
these upstream projects, and it integrates them without modifying their source
code.

License

Orichum is licensed under the Apache License 2.0. See
NOTICE for Orichum attribution and
third-party notices for the independent tools and
content it integrates.

References

• Claude Code LLM gateway configuration
• Claude Code status-line configuration
• LeanCTX documentation
• CLIProxyAPI
• Claudex
• mcp-atlassian documentation
• Orichum architecture