Painted Wolf Code is a local-first AI coding agent: a Tauri desktop app backed by a Go sidecar that is authoritative for sessions, tools, and workflows. The engine and repo codename is Lycaon (lycaon serve, lycaon/ paths) — see naming.
- Local-first — your code, sessions, and history stay on your machine. The sidecar is the authority for durable state; nothing reconstructs it from prose.
- Grounded results — tool receipts, evidence references, and verification let the host distinguish a supported claim from plausible prose. See grounding.
- Workflows with human control — declarative phases, gates, and approval checkpoints, composable from
.paintedwolf/project configuration. See workflows. - Parallel workers, isolated writes — workers receive bounded tasks in private overlays; reviewed results are promoted, never merged blindly. See coordination.
- Security by construction — attached roots define read/write scope, egress is mediated, approvals are requested when an effect needs authority. See security.
- Extensible — first-party Go tools, confined MCP providers, detection packs, and extension packs; composition is data, not runtime branches. See extend.
The public release target is macOS 14 (Sonoma) or later on Apple Silicon. Each release run also builds candidate Linux packages, a .deb and an .rpm for x86_64 and aarch64, retained as workflow artifacts; they are not published, linked, or offered through the updater. Windows x86_64 is a candidate catalog entry that release runs do not build. Platform and publication-state SSOT: packaging/release-platforms.json; release details: docs/dev-tasks.md.
Sessions that survive everything. A session is a durable conversation and execution boundary — ordered entries, workflow lineage, evidence, and recovery. Live tokens are a display projection; searchable transcript state waits for settlement. See session.
The host owns consequential state. Workflows, tools, permissions, persistence, and recovery are sidecar decisions; the desktop app renders and requests, it does not reconstruct policy. Design principles: docs/README.md.
Project-scoped trust. A project is a durable identity over one or more attached roots. .paintedwolf/ overlays configure guidance, workflows, and rules — commit-worthy configuration, versioned with your code. See project overlay.
Evidence over assertion. Every consequential result binds to receipts: source revisions, command outcomes, citations, and verification status recorded in the session ledger. See grounding.
Painted Wolf Code ships as a desktop app. Releases are published on the Releases page; Linux candidates are built per release but not linked or offered through the updater.
Linux packages (.deb, .rpm and pacman) are release candidates: no package repository is published yet. A package installed from a candidate file receives no updates through the package manager until its signed repository is configured. The app never installs anything itself. It reports a newer release from its channel, and says whether the configured package source offers that release, rather than printing an upgrade command. Supported distribution releases are listed in the Linux capability contract.
The package installs the engine under /opt/painted-wolf-code, the pw and pw-logs commands in /usr/bin, and a desktop entry; it needs kernel 6.2+, glibc 2.39+, and WebKitGTK 4.1 (2.44+). See Linux packages.
- Download the release for your platform from the Releases page.
- Launch the app. The Go sidecar starts with it — no separate service to run.
- Attach a project root and start a session.
Configuration lives under ~/.config/paintedwolf/. Every /v1/* route requires Authorization: Bearer <token> — loopback is not a trust boundary here. Boundary details: docs/security.md.
Prerequisites: Go, Bun, Node, and Rust with Cargo, at the versions pinned in lycaon/go.mod, .bun-version, .node-version, and rust-toolchain.toml; ./task setup-dev checks them. macOS development also needs Xcode Command Line Tools (xcode-select --install). Full prerequisites and toolchain notes: docs/dev-tasks.md.
./task setup-dev # one-time complete toolchain/dependency setup
./task check-fast # the gate every pull request runsPrerequisites, the two-terminal Den dev loop, debug capture, and the full ./task catalog: docs/dev-tasks.md. Rules for agents working in this repo: AGENTS.md.
Start at the docs map — it indexes everything below and more.
| Path | Role |
|---|---|
lycaon/ |
Go backend (lycaon serve) |
lycaon-den/ |
Tauri + Solid.js desktop frontend |
docs/architecture.md |
The two binaries, the one turn loop, subsystem owners |
docs/security.md |
Threat model, confinement, trust boundaries |
docs/workflows.md |
Workflow phases, gates, human control |
docs/extend.md |
Packs, tool contribution, extension surfaces |
AGENTS.md |
Agent policy and dev commands |
New here: architecture covers the two binaries, the one turn loop, and subsystem owners — one authoritative operation outcome, distinct from invocation receipts, data parentage, and UI state.
Notable changes are tracked in CHANGELOG.md, following Keep a Changelog and Semantic Versioning for the host/desktop stream (VERSION + v* git tags).
If it has been useful to you, tell a colleague who would use it, or star this repository.
Reports are welcome. There is no support contract — no guaranteed reply, fix, or timeline.
Questions and ideas start in Discussions. Reproducible app bugs go to Issues — pick the form that fits. In-bounds agent mistakes have their own form; they are not automatically defects. Security vulnerabilities go to a private advisory, never a public issue.
REPORTING.md defines the routing and what a useful report contains · CONTRIBUTING.md defines the pull-request gate, currently collaborator-only while the first release stabilises · SECURITY.md · CODE_OF_CONDUCT.md.
Application code is Apache-2.0; first-party catalog YAML under lycaon/config/ (CC-BY-4.0), vendored engines, and the Painted Wolf marks carry their own terms — full map in docs/licensing.md.