lucy-cli 1.12.1

A small local JSONL agent harness
Documentation

Project purpose

Lucy is a lightweight local coding-agent harness for macOS and Linux. It connects an OpenAI-compatible Chat Completions provider or a Codex subscription provider and exposes a model-facing cmd tool, with both an interactive TUI and a JSONL session interface for automation powered by the same turn engine.

Installation

Prebuilt releases are available for Apple Silicon macOS, Intel macOS, and x86_64 Linux. The recommended installation method is Homebrew:

brew install jwoo0122/tap/lucy

The lucy-cli crate is also published on crates.io for Rust users:

cargo install lucy-cli

Prebuilt archives are available from the GitHub Releases page. After extracting the archive, place the lucy executable on your PATH.

On first run, Lucy creates $XDG_CONFIG_HOME/lucy/config.toml (or ~/.config/lucy/config.toml when XDG_CONFIG_HOME is unset or empty). Existing ~/.lucy/config.toml files are migrated once; sessions remain under ~/.lucy/sessions. Set llm.model and choose either OpenRouter API-key authentication or Codex subscription authentication. Existing configs without [auth] continue to use the legacy OpenRouter-compatible settings.

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

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

export OPENROUTER_API_KEY="..."

To use a ChatGPT plan through Codex, log in separately. Tokens are stored in Lucy's private credential store, not in config.toml or sessions:

lucy codex login
# ... use a Codex model in config.toml ...
lucy codex logout

Use this configuration for Codex:

[auth]
provider = "codex_subscription"

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

Usage

Run Lucy in a terminal to start the TUI. Use the release binary path when building from source:

lucy
# Or: ./target/release/lucy

Lucy automatically uses JSONL mode when either standard input or output is not a terminal. Use --tui or --jsonl to choose a mode explicitly.

printf '%s\n' '{"type":"message","text":"Inspect the project."}' | lucy --jsonl
lucy --session <session-id>
lucy --list-sessions

In the TUI, press Enter to send, Shift/Alt+Enter to insert a line break, and Esc to cancel the active turn. Enter or Tab selects a focused skill in the slash picker; then enter /<name> [args] to attach the saved SKILL.md snapshot for that skill to the next model request. The same slash picker includes the Lucy-owned /settings [ignored args], /session, and /exit commands.

Features

  • TUI and JSONL: Supports terminal chat and line-delimited JSON automation.
  • Streaming activity: Shows model output, reasoning wait states, tool calls/results, and cancellation status in the TUI.
  • Tool activity UI: Renders cmd as a compact one-line card. The main-agent ready/working indicator appears in the bottom status line, and the prompt border uses a left-to-right teal-to-green gradient.
  • Completion notifications: When a TUI turn becomes idle, Lucy sends a terminal-native OSC 777 desktop notification for completion, cancellation, or error when the terminal supports it; JSONL output is unchanged.
  • Safe local command execution: Runs trusted cmd shell commands from the session's starting directory with time and output limits. Commands may set background: true to return a background ID immediately; Lucy delivers the bounded completion result to the model automatically, including through a follow-up turn after the originating turn ends.
  • Agent process boundary: Other agents can invoke lucy --jsonl through cmd, capture the returned session_id, and continue the conversation with lucy --jsonl --session <id>. Lucy does not coordinate relationships between independent sessions.
  • Persistent sessions: Stores conversation history, provider settings, boot context, and skill snapshots as JSONL in ~/.lucy/sessions/ and supports resuming them.
  • Context and skills: Collects global $XDG_CONFIG_HOME/lucy/AGENTS.md (or ~/.config/lucy/AGENTS.md) plus project AGENTS.md/CLAUDE.md instructions and Agent Skills for new sessions. The model sees only skill metadata; explicit slash-prefixed skill-name invocations use the saved snapshot.
  • Automatic context compaction: At 95% estimated context usage, safely summarizes older complete turns with the configured model, retains recent context, and resumes the active turn without rewriting session history.
  • Credential protection: OpenRouter API keys are read only from environment variables and are not written to configuration, sessions, the public protocol, or diagnostics. Codex subscription tokens are stored in Lucy’s private credential store and are never exposed to model tools or persisted sessions.