Lucy — The thin way to run powerful AI

Lucy is the thin line between powerful AI and your machine: one tool, one local process, no agent framework to carry.

brew install jwoo0122/tap/lucy

GitHub

Less in the way.
More work.

A single sharp edge

cmd is the only model-facing tool. The AI works through the shell it already understands, from your project directory, without a parallel suite of file tools.

No agent tuning layer

Lucy owns its built-in guidance. You choose the provider and model; there is no system prompt, orchestration graph, or plugin stack to tune and debug.

One stable boundary

Use the TUI directly or compose Lucy as a JSONL subprocess. Provider streams become normalized events, and named sessions resume across processes.

Connect your AI.
Start working.

Lucy keeps configuration to the connection: provider, model, credential. Its behavior ships with the binary.

Install Lucy

Prebuilt for Apple Silicon, Intel macOS, and x86_64 Linux.

brew install jwoo0122/tap/lucy

Choose the connection

First run creates one config file. Select an OpenAI-compatible provider with an environment key, or sign in with lucy codex login.

Run

Start the TUI in a terminal. Pipe JSONL and Lucy automatically becomes a machine interface over the same turn engine.

lucy

One file.
One connection.

First run creates ~/.config/lucy/config.toml, or uses $XDG_CONFIG_HOME. Set the provider and model; keep credentials outside the file.

OpenRouter

Use an OpenAI-compatible endpoint and name the environment variable that holds its API key.

config.toml

[auth]
provider = "openrouter"
api_key_env = "OPENROUTER_API_KEY"

[llm]
base_url = "https://openrouter.ai/api/v1"
model = "your-model"
# effort = "medium"

export OPENROUTER_API_KEY="..."

Codex subscription

Use a ChatGPT plan through the explicit Codex adapter. Login tokens stay in Lucy’s private credential store, not in config or sessions.

lucy codex login

config.toml

[auth]
provider = "codex_subscription"

[llm]
model = "gpt-5.3-codex"

→

Prefer the terminal? Open /settings while Lucy is idle to select a model and reasoning effort without editing TOML.

A terminal
or a protocol.

The same turn engine serves people and programs. Lucy chooses the interface from the terminal boundary, or you can select one explicitly.

Interactive

Run Lucy in a terminal for the TUI. Enter sends, Shift/Alt+Enter adds a line, and Esc cancels the active turn.

lucy

JSONL

Pipe a message for normalized line-delimited events. Standard output stays machine-readable; diagnostics go to standard error.

shell

printf '%s\n' '{"type":"message","text":"Inspect the project."}' \
  | lucy --jsonl

Resume

Sessions are append-only JSONL records. Keep the returned session ID to continue the same context from another process.