{"id":49849068,"url":"https://github.com/CruxExperts/localsetup","last_synced_at":"2026-05-16T11:00:53.756Z","repository":{"id":339288638,"uuid":"1122951787","full_name":"CruxExperts/localsetup","owner":"CruxExperts","description":"Universal cross-platform repo-local workflow engine for AI agents: context-as-code, reusable skills, and one-command install for Cursor, Claude Code, OpenAI Codex CLI, and OpenClaw.","archived":false,"fork":false,"pushed_at":"2026-05-09T03:49:42.000Z","size":7428,"stargazers_count":3,"open_issues_count":2,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-05-09T05:08:48.436Z","etag":null,"topics":["agentic-workflow","ai-agents","ai-workflows","codex-skills","context-as-code","cursor-skills","openclaw-skills"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/CruxExperts.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-12-25T22:34:41.000Z","updated_at":"2026-05-09T03:48:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/CruxExperts/localsetup","commit_stats":null,"previous_names":["cptnfren/localsetup","cruxexperts/localsetup"],"tags_count":6,"template":false,"template_full_name":null,"purl":"pkg:github/CruxExperts/localsetup","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CruxExperts%2Flocalsetup","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CruxExperts%2Flocalsetup/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CruxExperts%2Flocalsetup/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CruxExperts%2Flocalsetup/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/CruxExperts","download_url":"https://codeload.github.com/CruxExperts/localsetup/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/CruxExperts%2Flocalsetup/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33100319,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-16T04:41:52.686Z","status":"ssl_error","status_checked_at":"2026-05-16T04:41:52.009Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agentic-workflow","ai-agents","ai-workflows","codex-skills","context-as-code","cursor-skills","openclaw-skills"],"created_at":"2026-05-14T14:00:19.876Z","updated_at":"2026-05-16T11:00:53.750Z","avatar_url":"https://github.com/CruxExperts.png","language":"Python","funding_links":[],"categories":["Skills \u0026 Plugins"],"sub_categories":["Notable Skills \u0026 Plugins"],"readme":"# Localsetup v3\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/localsetup-v3-readme-hero.png\" alt=\"Localsetup v3 visual: repo-local agent workflow framework\" width=\"960\"\u003e\n\u003c/p\u003e\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\u003cimg src=\"https://img.shields.io/badge/license-MIT-blue.svg\" alt=\"License\"\u003e\u003c/a\u003e\n  \u003ca href=\"https://agentskills.io/specification\"\u003e\u003cimg src=\"https://img.shields.io/badge/Agent%20Skills-compatible-2ea44f\" alt=\"Agent Skills compatible\"\u003e\u003c/a\u003e\n  \u003ca href=\"_localsetup/docs/PLATFORM_REGISTRY.md\"\u003e\u003cimg src=\"https://img.shields.io/badge/platforms-cursor%20%7C%20claude--code%20%7C%20codex%20%7C%20openclaw%20%7C%20kilo%20%7C%20opencode-1f6feb\" alt=\"Supported platforms\"\u003e\u003c/a\u003e\n\u003c/p\u003e\n\n**Version:** 3.8.6\u003cbr\u003e\n\n**Localsetup v3 gives coding agents a repo-local operating layer.**\n\nAgent 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.\n\nLocalsetup v3 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.\n\nUse it when you want agents to stop improvising from hidden local setup and start working from auditable context that travels with the code.\n\n## The short version\n\nLocalsetup v3 packages:\n\n- Global framework source under `~/.local/share/localsetup/source` for installed users; source checkouts keep `_localsetup/` for contributors\n- 52 shipped capability skills plus 22 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\n- Cross-platform adapters for Cursor, Claude Code, OpenAI Codex CLI, OpenClaw, Kilo, and OpenCode\n- Agent Skills-compatible `SKILL.md` packages that can be imported, normalized, vetted, installed, and reused\n- Workflow packages under `_localsetup/workflows/` that stay executable as skills while carrying Localsetup `workflow.yaml` metadata for aliases, gates, dependencies, and generated registries\n- Documentation alignment tooling that inventories source-owned docs, maps code truth, audits generated facts, and refreshes supported public/generated surfaces\n- Context-index tooling for vector-first SQLite retrieval, freshness checks, agent preflight, MCP configuration support, and machine-readable worklists\n- A Python-first installer with preflight, planning, verification, rollback metadata, and generated docs sync\n- 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\n\nThat means your agent setup travels with the repo, survives context resets, and can be reviewed like code.\n\n## How it fits together\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/localsetup-v3-architecture.svg\" alt=\"Localsetup v3 architecture: repo source, config resolver, managed home library, adapters, and rollback metadata\" width=\"960\"\u003e\n\u003c/p\u003e\n\nThe 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.\n\n## Skills and workflow packages\n\nLocalsetup v3 makes one important distinction explicit:\n\n| Package type | Source root | Runtime shape | Use it for |\n|---|---|---|---|\n| 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. |\n| 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. |\n\nBoth 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.\n\nStart with the [workflow packages guide](_localsetup/docs/WORKFLOW_PACKAGES.md) for usage and the [workflow standard](_localsetup/docs/WORKFLOW_STANDARD.md) for authoring rules.\n\n## Current snapshot\n\n\u003c!-- facts-block:start --\u003e\n| Fact | Value |\n|---|---|\n| Current version | `3.8.6` |\n| Supported platforms | `cursor, claude-code, codex, openclaw, kilo, opencode` |\n| Shipped skills | `52` |\n| Workflow packages | `22` |\n| Source | `_localsetup/docs/_generated/facts.json` |\n\u003c!-- facts-block:end --\u003e\n\n## 60-second quickstart\n\nGlobal bootstrap from any directory on Linux, macOS, or WSL2:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/CruxExperts/localsetup/main/install | bash -s --\n```\n\nThis opens an interactive terminal wizard. It creates or refreshes the managed source checkout, explains what will be changed, lets you choose whether to attach agent adapters, and asks for confirmation before applying.\n\nEvery 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.\n\nThe wizard stays dependency-free and line-oriented. 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]`.\n\nThe legacy public form still opens the same wizard when a terminal is available:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/CruxExperts/localsetup/main/install | bash -s -- --yes --tools codex\n```\n\nRaw `main` bootstrap is the current development channel. For release verification, download the GitHub release tarball with its `.sha256` sidecar and run:\n\n```bash\npython3 _localsetup/tools/localsetup_v3.py --source-root . verify-release dist/localsetup-v$(cat VERSION).tar.gz\n```\n\nSelecting tools in the wizard, or passing `--tools` / `--platforms`, attaches adapters such as `.codex/skills` to the chosen target. If you do not select tools, the install is global-library-only.\n\nFor automation, opt in explicitly:\n\n```bash\ncurl -sSL https://raw.githubusercontent.com/CruxExperts/localsetup/main/install | bash -s -- --non-interactive --yes\n```\n\nAutomation mode preserves machine-readable output. Without a terminal, the installer asks you to rerun with a TTY or with `--non-interactive --yes`.\n\nLocalsetup 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.\n\nFrom a cloned checkout, open the same wizard:\n\n```bash\n./install --directory .\n```\n\nThe 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`. Both paths also create a managed user command at `~/.local/bin/localsetup`. After registration, run Localsetup from any project:\n\n```bash\nlocalsetup install --tools codex --yes\n```\n\nWhen 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.\n\nAttach adapters only for the hosts you choose:\n\n```bash\nlocalsetup install --tools codex,kilo --yes\n```\n\nInstall every shipped skill and workflow package for Codex, Kilo, and OpenCode, while preparing the managed Python dependency environment:\n\n```bash\n./install --directory . --tools codex,kilo,opencode --packs bootstrap,core,dev,ops,integrations,publishing,harness,experimental --install-deps\n```\n\nAttach a selected adapter to another repo while using this checkout as the source:\n\n```bash\n./install --directory /path/to/localsetup --target-directory /path/to/project --tools cursor\n```\n\nTo convert a repo that may contain old Localsetup files or adapter paths, start with a dry report and apply only after blockers are clear:\n\n```bash\nlocalsetup convert --tools codex --packs core\nlocalsetup convert --tools codex --packs core --yes\n```\n\nConversion 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.\n\nWindows support is WSL2-only in v3. Open WSL2, change to the repo path, and run the Bash installer.\n\nFull install docs: [_localsetup/docs/QUICKSTART.md](_localsetup/docs/QUICKSTART.md) and [_localsetup/docs/MULTI_PLATFORM_INSTALL.md](_localsetup/docs/MULTI_PLATFORM_INSTALL.md).\n\nOpt-in harness automation is documented separately because normal installs never schedule autonomous work. See [_localsetup/docs/HARNESS_AUTOMATION.md](_localsetup/docs/HARNESS_AUTOMATION.md) for `localsetup harness codex-heartbeat plan/init/enable/status/run/disable`.\n\n## 10 reasons to use Localsetup v3\n\n1. **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.\n2. **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.\n3. **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.\n4. **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.\n5. **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.\n6. **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.\n7. **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.\n8. **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.\n9. **It makes installs reversible.** The v3 installer plans, applies, verifies, writes lock/registry metadata, supports adapter detach, and can roll back managed paths without treating generated adapter output as source.\n10. **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.\n\n## Shipped packages worth starting with\n\nThese are not toy prompts. They are practical skills and workflows from the shipped library.\n\n| Package | Why it matters |\n|---|---|\n| `ls-agentlens` | Helps agents explore larger codebases through structured navigation instead of blind file-hopping. |\n| `ls-debug-pro` | Gives debugging a repeatable method across Node, Python, Swift, network issues, and git bisect. |\n| `ls-test-runner` | Guides test creation and execution across pytest, Jest, Vitest, Playwright, and XCTest. |\n| `ls-typescript-code-quality` | Guides TypeScript, TSX, tsconfig, typed linting, Node TypeScript scripts, and framework-heavy TypeScript changes. |\n| `ls-pr-reviewer` | Turns PR review into a structured risk hunt: diff analysis, security concerns, test gaps, and style issues. |\n| `ls-documentation-alignment` | Audits docs against implementation truth, generated facts, assets, and source-owned documentation surfaces. |\n| `ls-github-publishing-workflow` | Packages public GitHub readiness checks around docs, versioning, security policy, release evidence, and repository settings. |\n| `ls-mcp-builder` | Helps build high-quality MCP servers for current agent/tool interoperability workflows. |\n| `ls-skill-importer` | Imports skills from URLs or local paths with discovery, validation, security screening, and summaries. |\n| `ls-skill-vetter` | Reviews third-party skills as untrusted inputs before they join your agent environment. |\n| `ls-codex-heartbeat` | Initializes and runs opt-in heartbeat checks with transaction-safe artifacts and explicit cron activation. |\n| `ls-keepass-secrets` | Resolves logical secrets through KeePassXC with safe mapping files and redacted output defaults. |\n| `ls-cloudflare-dns` | Manages Cloudflare DNS through deterministic JSON plans, snapshots, dry runs, and guarded apply flows. |\n| `ls-workflow-ops-tmux-session` | Keeps human-controlled server operations visible, resumable, and sudo-aware. |\n\nSee the generated catalogs for all shipped skills and workflows: [_localsetup/docs/SKILLS.md](_localsetup/docs/SKILLS.md) and [_localsetup/docs/WORKFLOW_QUICK_REF.md](_localsetup/docs/WORKFLOW_QUICK_REF.md).\n\n## Install lifecycle\n\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"assets/localsetup-v3-install-lifecycle.svg\" alt=\"Localsetup v3 install lifecycle: doctor, configure, context, plan, install, verify, ship, and rollback\" width=\"960\"\u003e\n\u003c/p\u003e\n\nThe Bash wrapper stays thin. The Python CLI handles preflight, dependency setup, adapter planning, managed skill installation, verification, generated docs, packaging, and rollback.\n\nUseful commands:\n\n```bash\nlocalsetup doctor\nlocalsetup verify --tools codex --level filesystem\nlocalsetup diff --tools codex\nlocalsetup skill search context\nlocalsetup workflow info ls-workflow-audit-framework\nlocalsetup why --packs core\nlocalsetup graph\nlocalsetup adopt --target-directory .\nlocalsetup sbom --out /tmp/localsetup-source.cdx.json\npython3 _localsetup/tools/localsetup_v3.py --source-root . context --markdown\npython3 _localsetup/tools/localsetup_v3.py --source-root . validate-catalog\npython3 _localsetup/tools/localsetup_v3.py --source-root . audit-global-first\npython3 _localsetup/tools/localsetup_v3.py --source-root . rollback\n```\n\nUse `--trace-json /path/to/events.jsonl` with `install`, `verify`, or `doctor` to append local JSONL trace events for automation review.\n\n## What Localsetup is solving\n\nAgent 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.\n\nLocalsetup'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.\n\nThe design follows a few durable pressures instead of chasing market snapshots:\n\n- Agents need repo-owned context, not only session memory.\n- Imported instructions and skills need supply-chain treatment before they are trusted.\n- Tool and data access should be explicit, least-privilege, and reviewable.\n- Long-running work needs checkpoints, validation evidence, and handoff notes.\n- Interoperability work such as [Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro) and [Agent Skills](https://agentskills.io/specification) is useful, but Localsetup keeps those integrations source-owned and replaceable.\n\n## Requirements\n\n- Python `\u003e= 3.10`\n- Bash on Linux, macOS, or WSL2\n- Git and network access to GitHub for raw bootstrap, unless installing from a local clone\n- Recommended: `rg`, `pip`, and the packages in `_localsetup/requirements.txt`; managed installs prefer `_localsetup/requirements.lock` with pip hash checking when present.\n\nUse managed dependency setup instead of system pip overrides:\n\n```bash\n./install --directory . --install-deps\n```\n\n## Read more\n\n- [Framework docs index](_localsetup/docs/README.md)\n- [Framework README](_localsetup/README.md)\n- [Feature catalog](_localsetup/docs/FEATURES.md)\n- [Platform registry](_localsetup/docs/PLATFORM_REGISTRY.md)\n- [Harness automation](_localsetup/docs/HARNESS_AUTOMATION.md)\n- [Workflow packages](_localsetup/docs/WORKFLOW_PACKAGES.md)\n- [Workflow standard](_localsetup/docs/WORKFLOW_STANDARD.md)\n- [Workflow registry](_localsetup/docs/WORKFLOW_REGISTRY.md)\n- [Skill importing](_localsetup/docs/SKILL_IMPORTING.md)\n- [Skill discovery](_localsetup/docs/SKILL_DISCOVERY.md)\n- [Contributing](CONTRIBUTING.md)\n- [Support](SUPPORT.md)\n- [Code of conduct](CODE_OF_CONDUCT.md)\n- [Security](SECURITY.md)\n\n## License\n\nLocalsetup is released under the [MIT License](LICENSE).\n\n## Community and Support\n\nFor 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.\n\nUse [GitHub Discussions](https://github.com/CruxExperts/localsetup/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.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCruxExperts%2Flocalsetup","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FCruxExperts%2Flocalsetup","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FCruxExperts%2Flocalsetup/lists"}