Localsetup

Version: 4.1.6

Localsetup gives coding agents a repo-local operating layer.

Agent work is moving from one-off prompts into repeatable development operations. The hard part is not only giving an agent more context; it is keeping that context durable, reviewable, portable across tools, and safe enough for real repositories.

Localsetup turns your repository into the source of truth for agent instructions, skills, workflow packages, adapter configuration, safety gates, install state, documentation truth, and release evidence. It is not another chat prompt collection. It is a portable framework with adapters for Cursor, Claude Code, OpenAI Codex CLI, OpenClaw, Kilo, and OpenCode, plus a disciplined package library and predictable controller workflow model.

Use it when you want agents to stop improvising from hidden local setup and start working from auditable context that travels with the code.

The short version

Localsetup packages:

• Global framework source under ~/.local/share/localsetup/source for installed users; source checkouts keep _localsetup/ for contributors
• 72 shipped capability skills plus 23 first-class workflow packages for debugging, testing, PR review, infrastructure, docs, git recovery, skill import, security vetting, context indexing, TypeScript code quality, opt-in harness automation, and agent workflow control
• Cross-platform adapters for Cursor, Claude Code, OpenAI Codex CLI, OpenClaw, Kilo, and OpenCode
• Agent Skills-compatible SKILL.md packages that can be imported, normalized, vetted, installed, and reused
• Workflow packages under _localsetup/workflows/ that stay executable as skills while carrying Localsetup workflow.yaml metadata for aliases, gates, dependencies, and generated registries
• Documentation alignment tooling that inventories source-owned docs, maps code truth, audits generated facts, and refreshes supported public/generated surfaces
• Context-index tooling for vector-first SQLite retrieval, freshness checks, agent preflight, MCP configuration support, and machine-readable worklists
• A Python-first installer with preflight, planning, verification, rollback metadata, and generated docs sync
• Opt-in harness automation for Codex heartbeat and repo-finalizer workflows, plus human-in-the-loop operations for risky commands, remote/server work, and sudo-aware tmux sessions

That means your agent setup travels with the repo, survives context resets, and can be reviewed like code.

How it fits together

The registered Localsetup source checkout is the canonical framework source. The installer resolves configuration, creates the managed package library for skills and workflow packages, attaches only explicitly selected target adapter paths, writes target lock/report metadata under .localsetup/, and records an install journal under .localsetup/install-journal/. Consuming repos do not receive a copied _localsetup/ by default.

Skills and workflow packages

Localsetup makes one important distinction explicit:

Package type	Source root	Runtime shape	Use it for
Capability skill	_localsetup/skills/ls-*	Agent Skills SKILL.md package	A reusable capability such as debugging, testing, skill import, PR review, service triage, or versioning.
Workflow package	_localsetup/workflows/ls-workflow-*	Agent Skills SKILL.md package plus workflow.yaml	A named orchestration flow with aliases, required skills, gates, phases, validation, and expected outputs.

Both package types install into ~/.local/share/localsetup/packages, so agent hosts can invoke them through explicitly attached adapter paths. The split keeps portable skills clean while making workflow orchestration auditable and generated from source manifests.

Start with the workflow packages guide for usage and the workflow standard for authoring rules.

Current snapshot

Fact	Value
Current version	4.1.6
Supported platforms	cursor, claude-code, codex, openclaw, kilo, opencode
Shipped skills	72
Workflow packages	23
Source	_localsetup/docs/_generated/facts.json

60-second quickstart

Global bootstrap from any directory on Linux, macOS, or WSL2:

curl -sSL https://raw.githubusercontent.com/CruxExperts/localsetup/main/install | bash -s --

This opens an interactive terminal wizard. The raw bootstrap wrapper checks the latest stable GitHub release, falls back to the latest stable-looking tag when the release API is unavailable, creates or refreshes the managed source checkout from that ref, explains what will be changed, lets you choose the managed package-library baseline and optional repo adapters, and asks for confirmation before applying.

Every wizard step shows the same shortcuts before you answer: Enter number(s) | d details | b back | q quit | ? help. Detailed mode is on by default, so menu rows explain what each choice does, when to choose it, and the tradeoff. Press d at any prompt for compact mode; compact mode still keeps the one-line summary for each option. Use q or Ctrl-C to quit; bare Esc is ignored so terminal arrow-key sequences do not cancel selection.

The wizard stays dependency-free and uses standard terminal controls. Multi-select screens use a checkbox UI in real terminals: move with arrows or j/k, press Space to toggle global packs, repo-visible packs, or platforms, and press Enter to accept. Scripted or non-TTY streams fall back to line-mode comma-separated choices. It uses semantic color and simple status glyphs only when the terminal supports them; NO_COLOR, TERM=dumb, non-TTY output, --no-color, and --color never keep output free of ANSI color. Use --color always or --glyphs unicode only for an interactive terminal where you explicitly want that rendering; --glyphs ascii keeps portable labels such as [OK], [WARN], and [FAIL].

The legacy public form still opens the same wizard when a terminal is available:

curl -sSL https://raw.githubusercontent.com/CruxExperts/localsetup/main/install | bash -s -- --yes --tools codex

The public command is release-backed even though the small wrapper is downloaded from main: managed bootstrap installs resolve the latest non-draft, non-prerelease GitHub release tag before cloning or refreshing ~/.local/share/localsetup/source, with a stable-tag fallback when release lookup is unavailable. Set LOCALSETUP_BOOTSTRAP_REF only when you intentionally want an explicit branch, tag, or commit. Explicit --directory checkouts are source-authoritative and are never auto-fetched or replaced.

For release verification, download the GitHub release tarball with its .sha256 sidecar and run:

uv run --locked python _localsetup/tools/localsetup.py --source-root . verify-release dist/localsetup-v$(cat VERSION).tar.gz

Selecting tools in the wizard, or passing --tools / --platforms, attaches adapters such as .codex/skills to the chosen target. For repo-targeted CLI automation with no platform or package selectors, Localsetup uses auto mode: existing Localsetup state is inferred and refreshed, safe legacy repairs are applied only when unambiguous, and a brand-new repo gets the suggested global package baseline with no repo adapter paths. Interactive installs first choose the global package-library baseline, defaulting to core or the prior registry setting. Repo setup is a separate choice; when selected, repo-visible packs default from the target lockfile or repo-detected suggestions.

For automation, opt in explicitly:

curl -sSL https://raw.githubusercontent.com/CruxExperts/localsetup/main/install | bash -s -- --non-interactive --yes

Automation mode preserves machine-readable output. Without a terminal, the installer asks you to rerun with a TTY or with --non-interactive --yes.

Localsetup CLI commands emit JSON by default unless a command has an explicit human-readable mode such as context --markdown. The --json config flag remains available when scripts want to make that output contract explicit.

From a cloned checkout, open the same wizard:

./install --directory .

The local checkout command uses that checkout as the registered source. Like the raw global bootstrap, it installs the managed skill library and creates no repo adapter paths unless you pass --tools or --platforms or run a repo-targeted auto-mode command. Both paths also create a managed user command at ~/.local/bin/localsetup. After registration, run Localsetup from any project:

localsetup plan --target-directory .
localsetup install --target-directory . --apply
localsetup update --target-directory .

When invoked through the managed command, Localsetup uses the registered framework checkout as the source and the nearest Git worktree root from your current directory as the target. Outside Git, it targets the current directory. Use --target-directory /path/to/project to override that target.

Attach adapters only for the hosts you choose:

localsetup install --tools codex,kilo --yes

Explicit selectors such as --platforms, --global-packs, --global-preset, --repo-packs, --repo-skills, --packs, or --skills bypass auto mode and keep the requested shape.

Tune the package footprint by preset, pack, taxonomy class, tag, individual skill, or exclusion:

localsetup install --tools codex --preset suggested --skill-classes development --skill-tags git --skills ls-context --exclude-skills ls-linux-patcher --yes

Presets are core, suggested, all, and custom. core is the conservative default for automation when no selector is provided; suggested starts with core plus repo-detected categories; all installs every shipped skill and workflow package; custom relies on the packs, classes, tags, and skills you name. --exclude-skills removes named skills from the resolved selection unless a selected workflow requires them. The legacy selector flags apply to both the managed global baseline and repo-visible adapter selection for compatibility. Use --global-packs / --global-preset and --repo-packs / --repo-preset when you want the managed library to contain a broader baseline than a target repo exposes.

Install every shipped skill and workflow package for Codex, Kilo, and OpenCode, while syncing the uv-managed Python dependency environment:

./install --directory . --tools codex,kilo,opencode --packs bootstrap,core,dev,ops,integrations,publishing,harness,experimental --sync-env

In symlink mode, Localsetup writes a scoped marker and managed per-package links inside each selected repo adapter path. The adapter directory itself remains a shared agent surface: custom skills, files, and non-Localsetup symlinks may live beside Localsetup-managed entries and must be preserved. That means a repo sees only the repo-visible Localsetup skills and workflow packages even when the global library contains a larger baseline. Portable mode uses the same scoped marker and package list, but copies selected managed packages instead of linking them. See _localsetup/docs/ADAPTER_OWNERSHIP.md for the ownership boundary.

Attach a selected adapter to another repo while using this checkout as the source:

./install --directory /path/to/localsetup --target-directory /path/to/project --tools cursor

To convert a repo that may contain old Localsetup files or adapter paths, start with a dry report and apply only after blockers are clear:

localsetup convert --tools codex --packs core
localsetup convert --tools codex --packs core --yes

Conversion writes a timestamped backup and machine-readable report under .localsetup/backups/conversion-*, archives known managed or legacy Localsetup artifacts, backs up and removes stale target _localsetup/ folders, blocks ambiguous unmanaged content, installs selected adapters, and verifies the result.

Windows support is WSL2-only in the current framework. Open WSL2, change to the repo path, and run the Bash installer.

Full install docs: _localsetup/docs/QUICKSTART.md and _localsetup/docs/MULTI_PLATFORM_INSTALL.md. Copy-paste command reference: _localsetup/docs/COMMAND_REFERENCE.md.

Opt-in harness automation is documented separately because normal installs never schedule autonomous work. See _localsetup/docs/HARNESS_AUTOMATION.md for localsetup harness codex-heartbeat plan/init/enable/status/budget/run/disable.

10 reasons to use Localsetup

1. Your agent context becomes code. Instructions, skills, workflows, platform manifests, and docs live in the repo, so changes are visible in git instead of hidden in a local profile or a forgotten prompt.
2. One skill library reaches multiple agent hosts. When selected with --tools or --platforms, the shipped adapters let Cursor, Claude Code, OpenAI Codex CLI, OpenClaw, Kilo, and OpenCode attach to the same managed Localsetup skill library.
3. It leans into portable skill packaging. Skills use spec-compatible SKILL.md frontmatter, which makes them easier to import, export, normalize, and share across ecosystems that understand the package shape.
4. It tackles the trust gap directly. The framework pushes agents toward repeatable workflows, explicit verification, documented assumptions, and human gates instead of one-off "looks good" responses.
5. It treats skill imports as supply-chain events. External skills are discovered, validated, security-screened, summarized, and normalized before they become part of your library.
6. It helps with the work developers actually hand agents. Debugging, tests, PR review, codebase navigation, docs cleanup, git recovery, MCP building, Linux service triage, patching, and release chores are covered out of the box.
7. It has safety rails for real machines. Server and operations workflows route through tmux, sudo probing, backup/safety guidance, and explicit approval points for risky actions.
8. It gives long-running work a shape. First-class workflow packages, decision trees, PRD queues, Agent Q handoffs, generated registries, and outcome templates make multi-step agent work easier to restart, audit, and delegate.
9. It makes installs reversible. The Localsetup installer plans, applies, verifies, writes lock/registry metadata, supports adapter detach, and can roll back managed paths without treating generated adapter output as source.
10. It keeps releases tidy. Version sync, generated facts, strict manifest schemas, checksum/SBOM sidecars, framework audit, and Conventional Commit release tooling reduce the drift that makes public repos feel abandoned.

Shipped packages worth starting with

These are not toy prompts. They are practical skills and workflows from the shipped library.

Package	Why it matters
ls-agentlens	Helps agents explore larger codebases through structured navigation instead of blind file-hopping.
ls-debug-pro	Gives debugging a repeatable method across Node, Python, Swift, network issues, and git bisect.
ls-test-runner	Guides test creation and execution across pytest, Jest, Vitest, Playwright, and XCTest.
ls-typescript-code-quality	Guides TypeScript, TSX, tsconfig, typed linting, Node TypeScript scripts, and framework-heavy TypeScript changes.
ls-pr-reviewer	Turns PR review into a structured risk hunt: diff analysis, security concerns, test gaps, and style issues.
ls-documentation-alignment	Audits docs against implementation truth, generated facts, assets, and source-owned documentation surfaces.
ls-github-publishing-workflow	Packages public GitHub readiness checks around docs, versioning, security policy, release evidence, and repository settings.
ls-mcp-builder	Helps build high-quality MCP servers for current agent/tool interoperability workflows.
ls-skill-importer	Imports skills from URLs or local paths with discovery, validation, security screening, and summaries.
ls-skill-vetter	Reviews third-party skills as untrusted inputs before they join your agent environment.
ls-codex-heartbeat	Initializes and runs opt-in heartbeat checks with transaction-safe artifacts and explicit cron activation.
ls-keepass-secrets	Resolves logical secrets through KeePassXC with safe mapping files and redacted output defaults.
ls-cloudflare-dns	Manages Cloudflare DNS through deterministic JSON plans, snapshots, dry runs, and guarded apply flows.
ls-workflow-ops-tmux-session	Keeps human-controlled server operations visible, resumable, and sudo-aware.
ls-workflow-tmux-terminal-mode	Manages tmux-default terminal mode setup and read-only health checks.

See the generated catalogs for all shipped skills and workflows: _localsetup/docs/SKILLS.md and _localsetup/docs/WORKFLOW_QUICK_REF.md.

Install lifecycle

The Bash wrapper stays thin. The Python CLI handles preflight, dependency setup, adapter planning, managed skill installation, verification, generated docs, packaging, and rollback.

Useful commands:

localsetup doctor
localsetup plan --target-directory .
localsetup install --target-directory . --apply
localsetup update --target-directory .
localsetup doctor repair --target-directory .
localsetup verify --tools codex --level filesystem
localsetup diff --tools codex
localsetup skill search context
localsetup workflow info ls-workflow-audit-framework
localsetup why --packs core
localsetup graph
localsetup adopt --target-directory .
localsetup sbom --out /tmp/localsetup-source.cdx.json
uv run --locked python _localsetup/tools/localsetup.py --source-root . context --markdown
uv run --locked python _localsetup/tools/localsetup.py --source-root . validate-catalog
uv run --locked python _localsetup/tools/localsetup.py --source-root . audit-global-first
uv run --locked python _localsetup/tools/localsetup.py --source-root . rollback

Use --trace-json /path/to/events.jsonl with install, verify, or doctor to append local JSONL trace events for automation review.

For a complete option table, see the command reference.

doctor reports the uv-managed source checkout environment. doctor repair emits a dry-run JSON repair report for legacy or partial target repos, and applies only low-ambiguity Localsetup-owned repairs when rerun with --yes. Repair now treats workflow packages as first-class inferred packages, preserves custom repo skills by default, and can emit compact handoff prompts with --agent-prompt or --emit-agent-prompt. Adapter-shaped directories such as .codex/skills and .agents/skills are shared surfaces, not Localsetup-exclusive directories; repair must preserve custom adapter content in place and mutate only proven Localsetup-managed entries. Clean legacy _localsetup/ framework trees are removed only after backup and, when tracked, git rm --cached; protected, custom, dirty, symlinked, or content-divergent _localsetup/ trees are preserved for migration planning. If doctor sees an old ~/.local/share/localsetup/venv from earlier releases, it reports that legacy venv as ignored and gives a repair hint instead of trying to execute it.

Release note for this repair behavior: .localsetup/lock.json is managed repo state and should stay visible to Git. Runtime summaries, journals, backups, health state, and context-index runtime data are local runtime state and are added to .git/info/exclude.

What Localsetup is solving

Agent tooling moves quickly, but the hard parts stay stubbornly practical. Teams still need context that survives across sessions, standards that work across tools, safety around imported instructions, and workflows that can be resumed by another human or agent without archaeology.

Localsetup's opinion is simple: keep the agent operating model close to the code. Make it installable. Make it reviewable. Make it boring enough to trust.

The design follows a few durable pressures instead of chasing market snapshots:

• Agents need repo-owned context, not only session memory.
• Imported instructions and skills need supply-chain treatment before they are trusted.
• Tool and data access should be explicit, least-privilege, and reviewable.
• Long-running work needs checkpoints, validation evidence, and handoff notes.
• Interoperability work such as Model Context Protocol and Agent Skills is useful, but Localsetup keeps those integrations source-owned and replaceable.

Requirements

• Python >= 3.12
• Bash on Linux, macOS, or WSL2
• Git and network access to GitHub for raw bootstrap, unless installing from a local clone
• Required for dependency sync: uv, with dependency intent in pyproject.toml and the committed uv.lock.
• Recommended: rg; GitHub/network access is needed for raw bootstrap unless installing from a local clone.

Use uv-managed dependency setup instead of system Python changes:

./install --directory . --sync-env

The default dependency mode is report-only. It can warn about corrupt legacy Localsetup environments, but it does not move files. Explicit sync paths such as --sync-env may quarantine only Localsetup-owned corrupt environments and then let uv rebuild the source checkout .venv; a target project's own .venv is never modified.

Read more

• Framework docs index
• Framework README
• Feature catalog
• Platform registry
• Harness automation
• Workflow packages
• Workflow standard
• Workflow registry
• Skill importing
• Skill discovery
• Contributing
• Support
• Code of conduct
• Security

License

Localsetup is released under the MIT License.

Community and Support

For bugs, use the bug report form and include the Localsetup version, platform ID, command, expected result, actual result, and validation output. For feature requests, use the feature form and name the affected skill, workflow package, platform, or docs area. For version-sync, generated-doc, publish, or package-artifact problems, use the maintenance form.

Use GitHub Discussions for usage questions and early design conversation. Report security-sensitive issues through private vulnerability reporting when available; otherwise open a minimal public issue asking for a secure contact without details.