Start with binary releases on macOS or Linux.
Work in progress
Guided shell runtime
OpenClue
OpenClue. The AI that guides you
OpenClue is a Unix-native GenAI and LLM CLI runtime for real shell workflows where control must stay deterministic. It brings guided planning, explicit permissions, and inspectable runtime state into the shell without trying to replace it.
- Experimental and still settling
- Install paths for macOS and Linux
- Explain-first onboarding with
--explain
Explain-first shell flow
$
oclue --explain "Summarize this repository"
Explain mode stays execution-free and shows how OpenClue would inspect the active root before running anything.
$
oclue status permissions overview
No grants yet. No hidden authority. Add permissions only when the task actually needs them.
$
oclue "Review the last 200 lines of build.log"
guided planning -> validation -> policy -> execution
Public source access is not the default install story yet.
oclue is primary. openclue stays compatible.
Core ideas
Why OpenClue exists
OpenClue is designed for teams and individuals who want serious AI assistance in the shell while keeping control surfaces inspectable, permissions reusable, and execution behavior deterministic.
Deterministic safety boundary
Planner output is treated as untrusted input. Commands run only after validation, policy checks, grant resolution, and sandbox preparation.
Unix-native by default
Payload stays on stdout, control chrome stays on the TTY or stderr,
and --io-mode=pipe keeps filter chaining clean.
Agentic without terminal lock-in
Sessions, shared context, reviewer loops, package-managed skills, and background execution add structure without turning the CLI into a fullscreen UI.
macOS + Linux
Built for the two supported host targets today.
Interactive + CI
The same runtime can assist in the shell and stop safely in automation when a required permission is still unresolved.
Explicit state
Status, permissions, sessions, and audit surfaces stay inspectable.
Visual language
Why the Honeyguide
OpenClue uses the honeyguide as its mascot because the metaphor matches the product: guide toward the important place, keep the path visible, and do not pretend to replace the operator.
The grey and olive tones with the yellow accent keep the brand shell-first, alert, and low-noise.
A guide, not a pilot
- The honeyguide finds the hive and leads others to it. OpenClue is meant to surface likely paths and root causes, not hide how it got there.
- It is cooperative by design: AI guides, the operator reviews scope, grants permissions, and decides what actually runs.
- The sharper posture fits the product goal: work through runtime and security questions with precision instead of noise.
Capabilities
What it can do
OpenClue is intentionally narrow in some places and richer in others: it focuses on trustworthy shell execution, config discipline, and inspectable agent workflows.
Plan, validate, repair
Generate a plan, reject malformed output, and use bounded repair retries before any command runs.
Permissions with memory
Reuse explicit permission scopes for commands, paths, and external targets instead of re-approving the same access again and again.
Explain-only mode
Run --explain when you want a non-executing explanation of how OpenClue would approach a task before anything runs.
Sessions and shared context
Keep ongoing shell work grounded in attached sessions and persisted context snapshots instead of loose prompt history.
Package-managed extensions
Install or upgrade agents, personas, skills, and config packages deterministically inside the active root.
Status, audits, and system checks
Inspect runtime state, permissions, sessions, capacity, and host prerequisites with read-only status commands.
Installation
Two straightforward ways to get started
Install via Homebrew on macOS or use release artifacts on Linux. Public install guidance stays on the binary paths that are actually available today.
macOS
Use the Homebrew tap and cask. The install adds oclue, openclue, and the Finder-visible app bundle.
brew tap juangamnik/openclue
brew install --cask openclueLinux
Download the matching release asset from the public distribution repo. Current artifacts are published as .deb, .rpm, and .tar.gz.
Full installation guide
Includes bootstrap commands, provider setup, and Linux package notes.
How it works
Use it in four deliberate steps
OpenClue keeps the model in the planning loop and the runtime in charge of authority, execution, and persistence.
Initialize a root
Choose global or repo mode and let bootstrap install the deterministic baseline packages.
oclue config init
oclue --repo-config config initProvide credentials or endpoints
Use root-local auth storage, session-scoped auth, or process environment variables.
oclue config auth set openai --session --api-key ...
oclue --provider openai --model gpt-5-mini --explain "Summarize this repository"Run a goal
OpenClue plans, validates, checks policy and grants, then executes only the accepted external steps.
oclue "Review the last 200 lines of build.log and propose the next fix"Inspect and refine
Check status surfaces, permissions, or background preflight output before widening scope.
oclue status overview
oclue status permissions overview
oclue --execution-mode background --preflight-permissions --result-json "..."Next steps
Install it, bootstrap a root, and start with --explain.
That path keeps the first interaction low-risk while still showing the mental model, output contract, and provider wiring.