Plan
The planner turns your goal into structured output rather than arbitrary shell text.
Using OpenClue
Keep the model in the planning loop and the runtime in charge.
The default command is oclue. Use openclue if you prefer the
longer alias, but the behavior stays the same. The mental model is simple: request work,
inspect or explain it, let policy and grants decide scope, then execute only what passes.
The project remains experimental, so the safest way in is to start narrow, use oclue help
to explore the command areas, and build trust from there.
Execution flow
What happens during a run
OpenClue follows a strict plan-to-execution sequence. The model proposes. The runtime validates, checks policy, resolves permissions, and then decides whether a step is allowed to run.
Validate and repair
Malformed plans are rejected, and bounded repair retries can request a corrected version.
Check policy and grants
Canonical command, path, URL, or email scopes are allowed, asked, or denied deterministically.
Prepare sandbox rules
Execution uses the host backend when available and fails closed if enforce-mode prerequisites are missing.
Execute
Commands are invoked directly, tool output streams line-by-line, and OpenClue's own status lines stay off payload stdout.
Persist context
Runs can update sessions and shared context so later work stays grounded in explicit state.
Command recipes
Start with explain mode, then widen scope deliberately
These examples show the typical path from safe inspection to richer execution.
Guided discovery
oclue help config
Start with oclue help, then drill down by topic when you need the next relevant command area.
Explain-only
oclue --explain "Summarize this repository"Explain mode uses a dedicated explain-only prompt path and never executes commands.
Normal interactive task
oclue "Review the last 200 lines of build.log and propose the next fix"This is the standard agent mode: planning, validation, policy checks, execution, and context update.
Background permission preflight
oclue --execution-mode background --preflight-permissions --result-json "Prepare a release checklist"Useful for CI or automation when you want deterministic missing-scope output without executing tools.
Pipe-friendly output
oclue --io-mode=pipe --explain "Summarize this repository"In pipe mode, OpenClue suppresses header, plan, and progress chatter so payload remains data-only.
Capabilities
What the runtime gives you beyond plain prompt-in, text-out
OpenClue is not trying to be the thinnest LLM wrapper. It adds structure where shell work benefits from reviewability, bounded automation, and persistent operational state.
Structured planning
Plans are emitted as structured Action-IR instead of trusted free-form shell snippets.
Reviewer pass
An optional reviewer can reject or replace a risky plan before execution begins.
Canonical grants
Permission prompts and reuse operate on deterministic command, path, domain, URL, and email scopes.
Sessions and contexts
Carry ongoing work across shells with explicit attachment, detachment, and context snapshots.
Config-guided package ecosystem
Install skills, agents, personas, and config packages inside the active root with deterministic upgrades.
Status surfaces
Inspect permissions, sessions, capacity, contexts, system prerequisites, and more through read-only commands.
Background automation
Use prompt-free execution with bounded replanning and machine-readable result JSON in CI-friendly flows.
TTY-aware UI
Interactive runs get headers, plan previews, and progress lines on the control stream while payload remains clean.
Modes
Execution and output are explicit contracts
OpenClue separates runtime prompt behavior from output shaping. That makes the CLI predictable in terminals, pipes, and automation environments.
| Setting | Values | What it changes |
|---|---|---|
--execution-mode |
interactive, trusted, background |
Prompt behavior and fail-closed handling for unresolved asks |
--io-mode |
interactive, pipe |
Whether control-stream chatter is rendered or suppressed for data-only flows |
--verbosity |
abstract, standard, technical |
How detailed human-readable narration should be |
--log-level |
quiet, info, debug, trace |
How much diagnostic output appears on stderr |
Interactive mode
Best for pair-shelling. Prompts, plan previews, and permission asks are available when needed.
Background mode
Best for automation. OpenClue stays prompt-free and fails closed when missing scopes cannot be resolved safely.
Operational workflow
Sessions, packages, and diagnostics
OpenClue's value is not just task execution. It also gives you a way to manage runtime state, add deterministic extensions, and inspect what the system currently believes.
Session and context lifecycle
oclue session start
oclue context create
oclue session attach <session-id>Use sessions when shell work spans multiple runs and should share context deliberately.
Install or inspect packages
oclue config pkg index
oclue config pkg install skill structured-data
oclue config pkg inspect skill structured-data --jsonPackages provide agents, personas, skills, and config artifacts under deterministic root scoping.
Read-only diagnostics
oclue status overview
oclue status permissions overview
oclue status system checkStatus surfaces are where you inspect current state before you widen permissions or automation scope.
Get started
Install first, then keep the first run narrow.
The lowest-friction path is: install, run config init, add provider auth, and start with --explain.