{"id":"f85a2461-16a6-4583-8107-0109c8a7b006","slug":"lionclaw","kind":"skill","name":"lionclaw","summary":"Lionclaw is a local control plane for AI coding agents. It runs AI agents as durable, auditable workers with explicit state, skills, channels, schedules, and bounded permissions.","owner":"moshthepitt","repoUrl":"https://github.com/moshthepitt/lionclaw","license":"MIT","licenseTier":"permissive","trust":"community","stars":19,"match":null,"fewStars":false,"format":"skill","createdAt":null,"addedAt":"2026-10-14T06:07:28.652Z","logoUrl":"https://avatars.githubusercontent.com/u/372073?v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["writing"],"tags":["agentic-ai","ai","ai-agents","codex","llm","openai","openclaw","openclaw-skills"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-14T06:57:07.086Z","sample":false,"url":"https://conduits.dev/tools/lionclaw","language":"Rust","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# LionClaw\n\nLionClaw runs real agent CLIs as project assistants.\n\nCodex is still Codex. OpenCode is still OpenCode. LionClaw is the local control\nplane around them: project identity, runtime configuration, durable sessions,\nlocal state, channels, scheduled work, and an audit trail.\n\nUse the agent harness you want. Keep the boundary around your project yours.\n\n```bash\ngit clone https://github.com/moshthepitt/lionclaw.git\ncd lionclaw\ncargo build --workspace --release\nexport PATH=\"$PWD/target/release:$PATH\"\n\ncd /path/to/your/project\nlionclaw doctor\n```\n\n`doctor` points at the next setup problem. Fix, rerun, repeat; when setup is\nready, run the command it prints next.\n\n## Why LionClaw\n\nAI is going to matter. Probably a lot.\n\nAnd if it is going to matter, then we should not sleepwalk into a future where\na handful of large companies own the agents, the memory, the tools, the\nworkflows, the credentials, the logs, and eventually the shape of the work\nitself. We have seen this movie before. It was called Web 2.0, and it ended\nwith everyone renting their own lives back from platforms.\n\nLionClaw is a small refusal of that future.\n\nThe model may be commercial. That is fine. The agent harness may be Codex,\nOpenCode, Claude Code, Gemini CLI, or something better that appears next month.\nAlso fine. But the boundary around the agent should belong to you: the project\nit runs in, the state it sees, the credentials it receives, the channels that\ncan reach it, the jobs it runs, and the audit trail it leaves behind.\n\nLionClaw keeps that boundary local, explicit, and swappable.\n\nThis matters because the future probably will not have one agent. It will have\nmany agent harnesses, each good at different things, each with its own strange\nlittle strengths and weaknesses. LionClaw gives one project a stable assistant\nhome while those runtimes come and go.\n\nIt is also intentionally small. Not because small is cute, but because small is\nauditable. Small can be understood. Small can be changed by one person with a\nweekend, a grudge, and a good enough reason.\n\nThat is the bet: real agents, local boundaries, user-owned control.\n\n## How LionClaw Works\n\nA LionClaw project is a normal project with a `.lionclaw/` directory.\n\nThat directory is the local control plane. It holds the project identity,\ninstances, runtime profiles, sessions, audit records, installed skills, channel\nbindings, jobs, and runtime-private state.\n\nWhen you run:\n\n```bash\nlionclaw run\n```\n\nLionClaw opens the project operator console when attached to a terminal. The\nconsole keeps the current context in the top ribbon and the everyday turn flow\nin one Run surface: durable transcript, prompt input, live runtime status, and\nrecent file-change feedback. On wide terminals, project objects stay visible\nbeside Run and the right column keeps the inspector and changed-files pane\nvisible together. Runtime stream detail is shown inline for the active turn and\nas inspectable activity instead of being mixed into the durable conversation.\n\nUse the plain line-oriented path when scripting or when a terminal UI is not\nwanted:\n\n```bash\nlionclaw run --plain\n```\n\nNon-terminal use automatically stays on the plain path.\n\nUse the selected runtime's own terminal UI when you specifically want the\nnative harness surface:\n\n```bash\nlionclaw run --runtime-tui\n```\n\nThat path still goes through LionClaw's runtime plan, mounts, staged auth,\npolicy-selected prompt context, and audit trail. LionClaw writes that context\ninto session-scoped runtime control state as both `AGENTS.generated.md` and the\nruntime-standard `AGENTS.md`. The runtime's native private home is mounted\nseparately at `/runtime/home` and persists across LionClaw sessions for the\nsame project, runtime, compatibility identity, and execution security shape\nincluding workspace access, network mode, install policy, secret mounts, and\nescape classes.\nFor Codex, LionClaw uses the outer container as the sandbox boundary and starts\nthe inner Codex UI without Codex's own sandbox/approval layer; launch-time Codex\nconfig overrides mark the container workspace as trusted and disable update\nchecks without rewriting the runtime-owned Codex config. Completed Codex and\nother native UI turns stay inside the runtime UI; attached mode does not import\nnative transcripts into LionClaw session history or alter continuation state\nused by kernel-managed turns, and it does not consume the saved\nruntime-session ready marker that later driven turns use. Prior LionClaw\nsession history is still included in the generated runtime context.\nLionClaw does not scrape terminal output.\nBecause this is the runtime's own TUI, there is no LionClaw command layer\ninside it. LionClaw slash controls such as `/lionclaw reset` are unavailable\nthere; use the normal `lionclaw run`, `run --plain`, or channel paths when you\nneed LionClaw-owned controls. Turn-scoped LionClaw features that require an\nactive kernel-managed turn, such as the program-backed `channel.send` bridge,\nor its MCP `channel_send` tool, are not projected into native runtime TUI\nsessions.\n\nThe selected runtime still does the agent work. LionClaw owns the boundary\naround it: the project it runs in, the state it sees, the mounts it receives,\nthe credentials that are staged, the durable session, and the record of what\nhappened.\n\nThat is the split: the runtime does the agent work. LionClaw decides where it\nruns, what it can see, and what gets recorded.\n\n## Set Up A Project\n\nRun `doctor` from the project you want LionClaw to own:\n\n```bash\ncd /path/to/your/project\nlionclaw doctor\n```\n\nFollow the repair commands until `doctor` reports no blocking setup issues.\nThen run the configured runtime:\n\n```bash\nlionclaw run\n```\n\nIn a terminal, `run` opens the operator console. Use `lionclaw run --plain`\nfor the line-oriented interactive path, or `lionclaw run --runtime-tui` to\nattach directly to the selected runtime's own terminal UI inside the LionClaw\nboundary. Interactive terminal launches resume the latest LionClaw session by\ndefault; pass `--new-session` to start a fresh LionClaw session while keeping\nthe persistent runtime-native home.\n\nInside the console, `Tab` and `Shift+Tab` move between Run and controls.\n`Ctrl+O` focuses controls, `Left` and `Right` cycle project, runtime, boundary,\nactivity, audit, and files, `Ctrl+X` maximizes Run or the active control pane,\n`Ctrl+P` opens commands and help, `Ctrl+C` interrupts an active turn, and\n`Ctrl+D` exits when idle. `Enter` submits the prompt or activates a selected\nproject item when project controls are active. After a prompt is submitted,\nRun remains the active scroll surface; typing printable text continues prompt\nediting in that same surface.\n\nFor Codex, use a logged-in Codex CLI and run LionClaw where the `podman`\nexecutable is available. If `run` reports a missing runtime image, build or\nprovide the image named in the error. The bundled image definition lives at\n`containers/runtime/Containerfile`. That default image is intentionally\nuseful for everyday assistant work: it includes Codex, OpenCode, git, ripgrep,\ncurl, jq, Python, archive helpers, PDF text tools, and ffmpeg/ffprobe for\nbasic media inspection without bundling browsers, SDKs, OCR language packs, or\nlocal model weights.\n\nContainer image recipes, including the Rust-enabled LionClaw development image,\nare documented in `containers/README.md`.\n\n`doctor` checks setup and prints the next run command when setup is no longer\nblocked. `run` checks launch. Use `lionclaw --help` and subcommand `--help`\nfor current syntax.\n\nRuntime auth stays runtime-specific. LionClaw stages only the runtime-local auth\nfiles needed for the confined launch.\n\nConfined runtime layout:\n\n- `/workspace`: selected work root\n- `/runtime`: session-scoped LionClaw runtime control state\n- `/runtime/home`: persistent runtime-native private home\n- `/drafts`: project-scoped draft/output area\n- `/lionclaw/project/instances.json`: read-only project instance inventory,\n  present for project-backed program runtimes\n- `/lionclaw/skills/<alias>`: installed non-channel skill assets\n- `/mnt/<target>`: optional operator-configured extra directories\n\n`/runtime/home` can contain runtime auth, config, databases, caches, and\nhistory. LionClaw does not treat the whole native home as an artifact or\n`channel.send` attachment root; only runtime control state and explicit\ngenerated-artifact directories are exportable.\n\nNetwork policy is intentionally coarse today: `on` or `none`. `on` uses the\nPodman network namespace, not host networking.\n\nExtra runtime mounts are explicit runtime-profile state. Use a short target\ntoken for the normal `/mnt/<token>` path, or an absolute container target when\nneeded:\n\n```bash\nlionclaw runtime mount add codex docs --source /absolute/docs\nlionclaw runtime mount add codex /reference/docs --source /absolute/docs --read-write\nlionclaw runtime mount list codex\nlionclaw runtime mount remove codex docs\n```\n\nMounts default to read-only. LionClaw rejects files, missing directories,\nproject/work-root metadata and instance-state paths, duplicate targets, and\nreserved runtime paths such as `/workspace`, `/runtime`, `/drafts`,\n`/attachments`, `/lionclaw`, `/run/secrets`, `/proc`, `/sys`, and `/dev`.\nPodman bind-mount arguments must also be representable: commas are accepted\nonly when neither the source nor target path requires the `--mount` form by\ncontaining `:`.\n\n## Projects And Instances\n\n`lionclaw project init` creates `.lionclaw/project.toml` and a default `main`\ninstance at `.lionclaw/instances/main`. A project is the local management\nboundary. An instance home stores one LionClaw instance's config, database,\nlogs, installed skills, runtime-private state, drafts, and assistant-home\ncontinuity.\n\nEach project instance records a default work root. `project init` points `main`\nat the project root, and `instance create <name>` does the same unless you pass\n`--work-root PATH`. The confined runtime sees the selected work root at\n`/workspace`.\n\nProject-backed runtimes also receive `LIONCLAW_PROJECT_INSTANCE` and\n`LIONCLAW_PROJECT_INSTANCES_FILE`. The file is a read-only generated projection\nof configured project instance names, not a mount of raw `.lionclaw` metadata.\nWhen the active preset allows program-backed `channel.send`, the same projection\ncan include restart-bound neighbor contact status; only configured neighbor\nroutes expose channel and provider refs.\n\nProject instances can expose preferred contacts through channel skill config.\nChannel-specific setup, routing behavior, and transport notes live with the\nowning skill under `skills/`.\n\nWithout `--home` or `--project`, LionClaw discovers only the current directory\nand its immediate parent. Use `--home PATH` when you need to target one exact\ninstance home and bypass project discovery. Use `lionclaw instance --help` for\nthe current instance commands.\n\n## Channels And Background Work\n\nChannels are skills that run outside the Rust core. They connect LionClaw to a\ntransport without baking provider-specific behavior into the trusted kernel.\n\nInteractive channels run in the current terminal. Background channels are\nmanaged through the platform backend and store declared channel env in the\nselected instance home, not in accidental shell state.\n\nUse `lionclaw up` when you want LionClaw to stay reachable after the current\nterminal is gone. Use command help for current channel and background syntax.\nUse the owning skill docs under `skills/` for channel-specific setup and\noperations.\n\n## Jobs\n\nJobs run time-based prompts in fresh isolated sessions and can deliver the\nfinal result through a configured channel.\n\nThey are configured through `lionclaw job`. Use `lionclaw job --help` for the\ncurrent command surface.\n\n## Doctor\n\n`lionclaw doctor` is read-only. It diagnoses target resolution, project state,\nruntime config, channels, managed units, and configured bind drift without\nallocating ports, starting units, stopping units, or changing files.\n\nIf no project exists in the current directory or its immediate parent, `doctor`\ntreats the current directory as the diagnostic target, reports `no LionClaw\nproject found`, and tells you how to initialize it.\n\nFindings render as stable runbook entries:\n\n```text\n[LC-D001] error: configured bind is occupied\ntarget: instance main configured bind 127.0.0.1:8787\nexpected: no listener, or the owned managed daemon for this instance\nobserved: 127.0.0.1:8787 is used by a non-LionClaw process\ninspect: ss -ltnp '( sport = :8787 )'\nnote: stop the process shown by inspect\n```\n\nInfo and warnings are advisory and exit 0. Errors exit 1, and internal doctor\nfailures exit 2.\n\n## Requirements\n\n`lionclaw run` currently supports Unix-like systems. Managed background paths,\nincluding `lionclaw up` and background channels, currently require Linux with a\nsystemd user manager.\n\n## State Layout\n\nProject-local state lives under `.lionclaw/`:\n\n- `project.toml`\n- `instances/main/`\n- `instances/<name>/`\n\nEach instance home contains:\n\n- `db/lionclaw.db`\n- `config/lionclaw.toml`\n- `config/instance.toml`\n- `config/channels/<channel>.env`\n- `config/runtime-secrets.env`\n- `skills/<alias>/`\n- `workspaces/main/`\n- `runtime/`\n- `units/`\n\n## Docs\n\n- [Architecture](docs/ARCHITECTURE.md) - trusted core, runtime boundary, channels, scheduler, audit, and API contracts\n- [Manual QA](docs/MANUAL_QA.md) - repeatable live acceptance checklist\n- [Release Process](docs/RELEASE.md) - release preparation and publishing\n- [Scripts](scripts/README.md) - developer and CI smoke helpers\n\n## License\n\nMIT. See [LICENSE](LICENSE).\n"}