OSA Claude Code

An open-source AI coding agent for your terminal, built in Elixir.
Understands your codebase, executes tasks, handles git workflows — all through natural language.
Built on the BEAM for real concurrency and fault tolerance.

---

Quick Install

git clone https://github.com/Miosa-osa/osa-claude-code.git
cd osa-claude-code
mix deps.get && mix compile

Then set your API key and run:

export ANTHROPIC_API_KEY=sk-ant-...
mix run --no-halt

Other ways to run

# One-shot query
mix run -e 'ClaudeCode.query("what files are in this directory?")'

# Build standalone binary
mix escript.build
./claude_code

Requirements

• Elixir 1.17+
• Erlang/OTP 26+

---

Model Providers

Supports five API providers out of the box. Set the corresponding environment variable to switch — no code changes needed.

Anthropic (Default)

export ANTHROPIC_API_KEY=sk-ant-...

OpenAI

export CLAUDE_CODE_USE_OPENAI=1
export OPENAI_API_KEY=sk-...

AWS Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_REGION=us-east-1

Uses your standard AWS credentials (environment variables, ~/.aws/config, or IAM role).

Google Cloud Vertex AI

export CLAUDE_CODE_USE_VERTEX=1

Uses Google Cloud Application Default Credentials (gcloud auth application-default login).

OpenRouter

export CLAUDE_CODE_USE_OPENROUTER=1
export OPENROUTER_API_KEY=...

Ollama (Local)

export CLAUDE_CODE_USE_OLLAMA=1

Provider Summary

Provider	Env Variable	Auth
Anthropic (default)	—	ANTHROPIC_API_KEY or OAuth
OpenAI	CLAUDE_CODE_USE_OPENAI=1	OPENAI_API_KEY or OAuth
AWS Bedrock	CLAUDE_CODE_USE_BEDROCK=1	AWS credentials
Google Vertex	CLAUDE_CODE_USE_VERTEX=1	gcloud ADC
OpenRouter	CLAUDE_CODE_USE_OPENROUTER=1	OPENROUTER_API_KEY
Ollama	CLAUDE_CODE_USE_OLLAMA=1	Local

---

Features

Tools (40)

File operations, shell execution, search, agents, MCP, and more:

Tool	Description
Bash	Shell command execution with safety checks
FileRead / FileWrite / FileEdit	Read, create, and modify files
Glob / Grep	File search by pattern, content search by regex
Agent	Spawn sub-agents for parallel task execution
WebFetch / WebSearch	Fetch URLs and search the web
MCPTool / ListMcpResources / ReadMcpResource	Model Context Protocol integration
LSP	Language Server Protocol queries
NotebookEdit	Jupyter notebook manipulation
TaskCreate / TaskGet / TaskList / TaskUpdate / TaskStop / TaskOutput	Task management
EnterPlanMode / ExitPlanMode	Planning mode
EnterWorktree / ExitWorktree	Git worktree navigation
AskUserQuestion	Interactive user prompts
TodoWrite	Todo list management
SendMessage	Message passing between agents
ToolSearch	Dynamic tool discovery
+ 10 more	Config, REPL, PowerShell, Cron, Teams, Remote, Sleep, Skill, Brief, SyntheticOutput

Commands (102)

Slash commands for every workflow: /compact, /config, /doctor, /memory, /permissions, /commit, /diff, /review, /export, /help, /init, /login, /model, /resume, /session, /status, /theme, /vim, /voice, and 83 more.

88 Feature Flags

Runtime-configurable via ETS. Includes ultrathink, voice mode, bridge mode, token budget tracking, agent triggers, team memory, bash classifier, and more.

Privacy Gateway

Optional built-in reverse proxy between you and the API:

config :claude_code, :privacy_gateway,
  enabled: true,
  port: 8888,
  upstream: "https://api.anthropic.com"

• Strips device IDs, emails, and local paths from outbound requests
• Suppresses telemetry by default
• Centralizes OAuth token management across devices
• /_health and /_verify admin endpoints

Native CCH Signing

For subscription users who want full access (fast mode, etc.) without a separate API key:

# config/config.exs
config :claude_code, :signature, mode: :native

Pure Elixir xxHash64 implementation — no compiled binaries or proxy needed. If you have a direct API key, you don't need this.

---

Fixes Over Upstream

Includes fixes from the open-source community:

• Session cache fix — preserves deferred_tools_delta attachments on session save so tools don't silently disappear on resume (#2638)
• Structured output retry cap — prevents infinite retry loops when structured output enforcement fails (MAX_STRUCTURED_OUTPUT_RETRIES=3)
• Earlier auto-compact — triggers context compaction before overflow (CLAUDE_AUTOCOMPACT_PCT_OVERRIDE=75)

---

Architecture

See ARCHITECTURE.md for the full breakdown.

lib/claude_code/
  application.ex        OTP supervision tree
  cli.ex                Entry point
  session.ex            Session GenServer
  query/                Query engine + streaming
  tools/                40 tools (50 files)
  commands/             102 commands (104 files)
  services/
    api/                Multi-provider client + signing
    oauth/              OAuth PKCE flows
  views/                Terminal UI (19 modules)
  privacy/              Privacy gateway
  utils/                Core utilities (254 files)
  features/             88 feature flags
  hooks/                Event hooks (15 files)
  bridge/               IDE integration (31 files)
  mcp/                  Model Context Protocol
  memory/               Persistent memory
  state/                App state management

Why Elixir

	TypeScript	Elixir
Concurrency	Single-threaded event loop	Millions of lightweight BEAM processes
Terminal UI	React + Ink (485 files)	term_ui (1 dep, 19 modules)
Agent processes	Child processes	Supervised BEAM processes with auto-recovery
Dependencies	npm (hundreds)	~20 hex packages
Fault tolerance	Crash kills the session	Supervisors restart failed components
Source files	1,902	702

---

Contributing

Contributions welcome.

1. Fork the repository
2. Create a feature branch (git checkout -b feat/my-feature)
3. Commit your changes
4. Open a Pull Request

---

Credits

• paoloanzn/free-code — community patterns, Codex integration, feature flag system
• motiful/cc-gateway — privacy gateway architecture
• pcharbon70/term_ui — Elm-style terminal UI framework
• @ssslomp — CCH signing research

License

TBD