🤝 HomieCode

your coding homie in the terminal. a fast, single-binary coding agent written in Rust — the agent isn't a tool, it's your friend who happens to be a terrifyingly good engineer. it reads the code before it touches it, tells you straight up when something breaks, and grinds on your goal until it's actually done.

slash /goal · up to 3 subagents · Kimi Code + ChatGPT (Codex) login · skills · a brainrot-but-precise TUI · an Electron desktop app

---

why

There are two harnesses worth stealing from: pi (clean agent loop, skills, tree sessions, wide provider support) and Codex (rock-solid Rust engine, device-flow auth, streaming, retries). HomieCode takes the best ideas from both, keeps the whole thing in one small Rust workspace, and gives it a personality: it's your homie.

the monorepo

crate / package	what it is
homie-core	the engine — providers (Anthropic + OpenAI-compatible streaming), the agent loop, sessions, skills, config, model auto-detection
homie-auth	credential store (~/.homiecode/auth.json, 0600), Kimi API keys, ChatGPT/Codex device-flow OAuth with token refresh
homie-tools	built-in tools: read write edit bash grep find ls + subagent (max 3, depth-guarded)
homie-tui	the homie binary — a ratatui terminal UI, plus headless (-p) and JSON (--json) modes
homie-app	the Electron desktop app, over the same engine via the --json protocol

Everything HomieCode owns on disk lives under $HOME/.homiecode/:

~/.homiecode/
  config.toml        # defaults, providers, agent settings
  auth.json          # credentials (mode 0600)
  sessions/          # one JSONL file per session, per project
  skills/            # drop-in Agent Skills (think-like-physicist ships here)
  commands/          # custom slash commands

quickstart

# build the binary
cargo build --release

# put it on your PATH (or run ./target/release/homie)
install -m755 target/release/homie ~/.local/bin/homie

# log in — ChatGPT/Codex device flow…
homie          # then type: /auth codex
# …or a Kimi key:
homie          # then type: /auth kimi <YOUR_KIMI_API_KEY>

# pick a model (auto-detected from whatever you're logged into)
# then just talk to your homie

Prefer a key in the environment? Any of KIMI_API_KEY, MOONSHOT_API_KEY, OPENAI_API_KEY, ANTHROPIC_API_KEY, OPENROUTER_API_KEY, DEEPSEEK_API_KEY, GROQ_API_KEY are picked up automatically.

the moves (slash commands)

command	what it does
/goal <text>	lock a goal — the homie keeps working across turns until it's genuinely done
/model	pick a model, auto-detected from your providers
/models	refresh the model list from every provider you're logged into
/auth <provider>	log in — codex for ChatGPT device login, else paste a key
/skills	list installed skills
/think-like-physicist	install + arm physicist mode (see below)
/new · /sessions	fresh session · resume a past one
/yolo	run spicy commands without asking
/help · /quit	the moves · dip

Any skill in ~/.homiecode/skills is also callable as /<skill-name>.

the headline feature: think like a physicist

/think-like-physicist installs a skill inspired by the Schema harness — the one that scored ~99% on ARC-AGI-3 by treating games that never state their rules like a physics problem. HomieCode generalizes it to any task: ground what the state actually is, encode a runnable model of how it behaves, verify that model against all the evidence before acting, and — the key move — when a prediction fails, be willing to change what the state is, not just patch the rule. Great for debugging, reverse-engineering, and unfamiliar systems.

subagents

Up to 3 subagents run at once (a semaphore enforces the cap). Each gets the coding tools but can't spawn its own subagents, and only its final answer comes back — clean fan-out for independent chunks of work.

the desktop app

cargo build --release
cd homie-app && npm install && npm start

Same engine, same identity, a real window. See homie-app/README.md.

docs

• docs/architecture.md — how the loop, providers, and sessions fit together
• docs/providers.md — providers, auth, and model detection
• docs/skills.md — writing your own skills
• docs/config.md — the config.toml reference

building from source

Needs a stable Rust toolchain (1.90+). cargo build --release produces the homie binary. CI builds it for Linux, Windows, and macOS (Intel + Apple Silicon) on every v* tag — grab a prebuilt binary from Releases.

license

MIT. we ball.