GitHub JavaScript Daily Trending Repositories

addyosmani/agent-skills

Production-grade engineering skills for AI coding agents.

Agent Skills

Production-grade engineering skills for AI coding agents.

Skills encode the workflows, quality gates, and best practices that senior engineers use when building software. These ones are packaged so AI agents follow them consistently across every phase of development.

  DEFINE          PLAN           BUILD          VERIFY         REVIEW          SHIP
 ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐      ┌──────┐
 │ Idea │ ───▶ │ Spec │ ───▶ │ Code │ ───▶ │ Test │ ───▶ │  QA  │ ───▶ │  Go  │
 │Refine│      │  PRD │      │ Impl │      │Debug │      │ Gate │      │ Live │
 └──────┘      └──────┘      └──────┘      └──────┘      └──────┘      └──────┘
  /spec          /plan          /build        /test         /review       /ship

Commands

8 slash commands that map to the development lifecycle. Each one activates the right skills automatically.

What you're doing	Command	Key principle
Define what to build	`/spec`	Spec before code
Plan how to build it	`/plan`	Small, atomic tasks
Build incrementally	`/build`	One slice at a time
Prove it works	`/test`	Tests are proof
Review before merge	`/review`	Improve code health
Audit web performance	`/webperf`	Measure before you optimize
Simplify the code	`/code-simplify`	Clarity over cleverness
Ship to production	`/ship`	Faster is safer

Want fewer manual steps once the spec exists? /build auto generates the plan and implements every task in a single approved pass — you approve the plan once, then it runs autonomously. It removes the human stepping between tasks, not the verification: every task is still test-driven and committed individually, and it pauses on failures or risky steps.

Skills also activate automatically based on what you're doing — designing an API triggers api-and-interface-design, building UI triggers frontend-ui-engineering, and so on.

Quick Start

Fastest path — any agent, one command. The open skills CLI installs into 70+ agents (Claude Code, Cursor, Codex, Copilot, Cline, and more):

npx skills add addyosmani/agent-skills            # install all 24 skills
npx skills add addyosmani/agent-skills --list     # browse before installing

Or grab individual skills:

npx skills add addyosmani/agent-skills --skill code-review-and-quality   # five-axis review before merge
npx skills add addyosmani/agent-skills --skill interview-me              # requirements interrogation, one question at a time
npx skills add addyosmani/agent-skills --skill test-driven-development   # red-green-refactor, enforced

Installing one skill? A per-skill npx install copies only skills/<name>/, not the repo-level references/ directory. The skill still works, but paths to supplementary shared checklists are unavailable. Use a whole-repo integration, clone the repository, or copy the needed checklist into a references/ directory inside the installed skill. This portability gap is tracked in #361.

Prefer a native integration? Pick your tool below.

Claude Code (recommended)

Marketplace install:

/plugin marketplace add addyosmani/agent-skills
/plugin install agent-skills@addy-agent-skills

SSH errors? The marketplace clones repos via SSH. If you don't have SSH keys set up on GitHub, either add your SSH key or use the full HTTPS URL to force HTTPS cloning during the marketplace-add step:
/plugin marketplace add https://github.com/addyosmani/agent-skills.git
/plugin install agent-skills@addy-agent-skills
If /plugin install still fails with git@github.com: Permission denied (publickey) on Windows or macOS, the recommended workaround is to configure Git once to rewrite GitHub SSH URLs to HTTPS for subprocess clones:
git config --global url."https://github.com/".insteadOf git@github.com:

Local / development:

git clone https://github.com/addyosmani/agent-skills.git
claude --plugin-dir /path/to/agent-skills

Cursor

Put workflow skills under .cursor/skills/ (sync from agent-skills/skills/) and short policies in .cursor/rules/*.mdc — do not paste full skills into rules. See docs/cursor-setup.md.

Antigravity CLI

Install as a native plugin for skills, subagents, and slash commands. See docs/antigravity-setup.md.

Install from the repo:

agy plugin install https://github.com/addyosmani/agent-skills.git

Install from a local clone:

git clone https://github.com/addyosmani/agent-skills.git
agy plugin install ./agent-skills

Gemini CLI

Install as native skills for auto-discovery, or add to GEMINI.md for persistent context. See docs/gemini-cli-setup.md.

Install from the repo:

gemini skills install https://github.com/addyosmani/agent-skills.git --path skills

Install from a local clone:

gemini skills install ./agent-skills/skills/

Windsurf

Add skill contents to your Windsurf rules configuration. See docs/windsurf-setup.md.

OpenCode

Uses agent-driven skill execution via AGENTS.md and the skill tool.

See docs/opencode-setup.md.

GitHub Copilot

Use agent definitions from agents/ as Copilot personas and skill content in .github/copilot-instructions.md. See docs/copilot-setup.md.

Kiro IDE & CLI

Skills for Kiro reside under ".kiro/skills/" and can be stored under Project or Global level. Kiro also supports Agents.md. See Kiro docs at https://kiro.dev/docs/skills/

Codex

Install as a native Codex plugin (Codex CLI v0.122+):

codex plugin marketplace add addyosmani/agent-skills
codex plugin add agent-skills@agent-skills

The first command registers the marketplace; the second installs the plugin. Codex reads the root skills/ directory directly through .codex-plugin/plugin.json. Once installed, invoke skills in chat using @ (e.g., @spec-driven-development). See docs/codex-setup.md for local installation and troubleshooting.

Command Code

Install natively with the built-in cmd skills command. Command Code clones the repo, discovers every SKILL.md, and installs into .commandcode/skills/:

cmd skills add addyosmani/agent-skills            # pick skills to install (project)
cmd skills add addyosmani/agent-skills --global   # install for all projects (~/.commandcode/skills/)
cmd skills add addyosmani/agent-skills -s spec-driven-development  # install a specific skill

Installed skills show up in the TUI slash menu, e.g. /spec-driven-development. See docs/commandcode-setup.md.

Other Agents

Skills are plain Markdown - they work with any agent that accepts system prompts or instruction files. See docs/getting-started.md.

Adoption

Already installed? How you roll the pack out depends on your codebase. The Adoption Guide covers two paths: the full lifecycle from day one for a greenfield project, or an incremental, verification-first rollout for an established codebase.

All 24 Skills

The commands above are entry points. The pack includes 24 skills total — 23 lifecycle skills plus the using-agent-skills meta-skill. Each skill is a structured workflow with steps, verification gates, and anti-rationalization tables. You can also reference any skill directly.

Meta - Discover which skill applies

Skill	What It Does	Use When
using-agent-skills	Maps incoming work to the right skill workflow and defines shared operating rules	Starting a session or deciding which skill applies

Define - Clarify what to build

Skill	What It Does	Use When
interview-me	One-question-at-a-time interview that extracts what the user actually wants instead of what they think they should want, until ~95% confidence	The ask is underspecified, or the user invokes "interview me" / "grill me"
idea-refine	Structured divergent/convergent thinking to turn vague ideas into concrete proposals	You have a rough concept that needs exploration
spec-driven-development	Write a PRD covering objectives, commands, structure, code style, testing, and boundaries before any code	Starting a new project, feature, or significant change

Plan - Break it down

Skill	What It Does	Use When
planning-and-task-breakdown	Decompose specs into small, verifiable tasks with acceptance criteria and dependency ordering	You have a spec and need implementable units

Build - Write the code

Skill	What It Does	Use When
incremental-implementation	Thin vertical slices - implement, test, verify, commit. Feature flags, safe defaults, rollback-friendly changes	Any change touching more than one file
test-driven-development	Red-Green-Refactor, test pyramid (80/15/5), test sizes, DAMP over DRY, Beyonce Rule, browser testing	Implementing logic, fixing bugs, or changing behavior
context-engineering	Feed agents the right information at the right time - rules files, context packing, MCP integrations	Starting a session, switching tasks, or when output quality drops
source-driven-development	Ground every framework decision in official documentation - verify, cite sources, flag what's unverified	You want authoritative, source-cited code for any framework or library
doubt-driven-development	Adversarial fresh-context review of every non-trivial decision in-flight - CLAIM → EXTRACT → DOUBT → RECONCILE → STOP, with optional user-authorized cross-model escalation	Stakes are high (production, security, irreversible), working in unfamiliar code, or a confident output is cheaper to verify now than to debug later
frontend-ui-engineering	Component architecture, design systems, state management, responsive design, WCAG 2.1 AA accessibility	Building or modifying user-facing interfaces
api-and-interface-design	Contract-first design, Hyrum's Law, One-Version Rule, error semantics, boundary validation	Designing APIs, module boundaries, or public interfaces

Verify - Prove it works

Skill	What It Does	Use When
browser-testing-with-devtools	Chrome DevTools MCP for live runtime data - DOM inspection, console logs, network traces, performance profiling	Building or debugging anything that runs in a browser
debugging-and-error-recovery	Five-step triage: reproduce, localize, reduce, fix, guard. Stop-the-line rule, safe fallbacks	Tests fail, builds break, or behavior is unexpected

Review - Quality gates before merge

Skill	What It Does	Use When
code-review-and-quality	Five-axis review, change sizing (~100 lines), severity labels (Nit/Optional/FYI), review speed norms, splitting strategies	Before merging any change
code-simplification	Chesterton's Fence, Rule of 500, reduce complexity while preserving exact behavior	Code works but is harder to read or maintain than it should be
security-and-hardening	OWASP Top 10 prevention, auth patterns, secrets management, dependency auditing, three-tier boundary system	Handling user input, auth, data storage, or external integrations
performance-optimization	Measure-first approach - Core Web Vitals targets, profiling workflows, bundle analysis, anti-pattern detection	Performance requirements exist or you suspect regressions

Ship - Deploy with confidence

Skill	What It Does	Use When
git-workflow-and-versioning	Trunk-based development, atomic commits, change sizing (~100 lines), the commit-as-save-point pattern	Making any code change (always)
ci-cd-and-automation	Shift Left, Faster is Safer, feature flags, quality gate pipelines, failure feedback loops	Setting up or modifying build and deploy pipelines
deprecation-and-migration	Code-as-liability mindset, compulsory vs advisory deprecation, migration patterns, zombie code removal	Removing old systems, migrating users, or sunsetting features
documentation-and-adrs	Architecture Decision Records, API docs, inline documentation standards - document the why	Making architectural decisions, changing APIs, or shipping features
observability-and-instrumentation	Structured logging, RED metrics, OpenTelemetry tracing, symptom-based alerting - instrument as you build	Adding telemetry, or shipping anything that runs in production
shipping-and-launch	Pre-launch checklists, feature flag lifecycle, staged rollouts, rollback procedures, monitoring setup	Preparing to deploy to production

Agent Personas

Pre-configured specialist personas for targeted reviews:

Agent	Role	Perspective
code-reviewer	Senior Staff Engineer	Five-axis code review with "would a staff engineer approve this?" standard
test-engineer	QA Specialist	Test strategy, coverage analysis, and the Prove-It pattern
security-auditor	Security Engineer	Vulnerability detection, threat modeling, OWASP assessment
web-performance-auditor	Web Performance Engineer	Core Web Vitals audit with Quick/Deep modes and a metric-honesty rule; run it via `/webperf`

See docs/agents.md for the decision matrix, orchestration rules, and how personas compose with skills and slash commands.

Reference Checklists

Quick-reference material that skills pull in when needed:

Reference	Covers
definition-of-done.md	Project-wide standing bar every change clears, contrasted with per-task acceptance criteria
testing-patterns.md	Test structure, naming, mocking, React/API/E2E examples, anti-patterns (JavaScript/TypeScript)
security-checklist.md	Pre-commit checks, auth, input validation, headers, CORS, OWASP Top 10
performance-checklist.md	Core Web Vitals targets, frontend/backend checklists, measurement commands
accessibility-checklist.md	Keyboard nav, screen readers, visual design, ARIA, testing tools
observability-checklist.md	On-call questions, structured logging, RED/USE metrics, tracing, symptom-based alerting, pre-launch gate
orchestration-patterns.md	Endorsed multi-persona orchestration patterns, anti-patterns, and the "personas don't invoke personas" rule

How Skills Work

Every skill follows a consistent anatomy:

┌─────────────────────────────────────────────────┐
│  SKILL.md                                       │
│                                                 │
│  ┌─ Frontmatter ─────────────────────────────┐  │
│  │ name: lowercase-hyphen-name               │  │
│  │ description: Guides agents through [task].│  │
│  │              Use when…                    │  │
│  └───────────────────────────────────────────┘  │                                                                                                
│  Overview         → What this skill does        │
│  When to Use      → Triggering conditions       │
│  Process          → Step-by-step workflow       │
│  Rationalizations → Excuses + rebuttals         │
│  Red Flags        → Signs something's wrong     │
│  Verification     → Evidence requirements       │
└─────────────────────────────────────────────────┘

Key design choices:

Process, not prose. Skills are workflows agents follow, not reference docs they read. Each has steps, checkpoints, and exit criteria.
Anti-rationalization. Every skill includes a table of common excuses agents use to skip steps (e.g., "I'll add tests later") with documented counter-arguments.
Verification is non-negotiable. Every skill ends with evidence requirements - tests passing, build output, runtime data. "Seems right" is never sufficient.
Progressive disclosure. The SKILL.md is the entry point. Supporting references load only when needed, keeping token usage minimal.

Project Structure

agent-skills/
├── skills/                            # 24 skills (23 lifecycle + 1 meta)
│   ├── interview-me/                  #   Define
│   ├── idea-refine/                   #   Define
│   ├── spec-driven-development/       #   Define
│   ├── planning-and-task-breakdown/   #   Plan
│   ├── incremental-implementation/    #   Build
│   ├── context-engineering/           #   Build
│   ├── source-driven-development/     #   Build
│   ├── doubt-driven-development/      #   Build
│   ├── frontend-ui-engineering/       #   Build
│   ├── test-driven-development/       #   Build
│   ├── api-and-interface-design/      #   Build
│   ├── browser-testing-with-devtools/ #   Verify
│   ├── debugging-and-error-recovery/  #   Verify
│   ├── code-review-and-quality/       #   Review
│   ├── code-simplification/           #   Review
│   ├── security-and-hardening/        #   Review
│   ├── performance-optimization/      #   Review
│   ├── git-workflow-and-versioning/   #   Ship
│   ├── ci-cd-and-automation/          #   Ship
│   ├── deprecation-and-migration/     #   Ship
│   ├── documentation-and-adrs/        #   Ship
│   ├── observability-and-instrumentation/ # Ship
│   ├── shipping-and-launch/           #   Ship
│   └── using-agent-skills/            #   Meta: how to use this pack
├── agents/                            # 4 specialist personas
├── references/                        # 7 supplementary checklists
├── hooks/                             # Session lifecycle hooks
├── .claude/commands/                  # 8 slash commands (Claude Code)
├── .gemini/commands/                  # 8 slash commands (Gemini CLI)
├── commands/                          # 8 slash commands (Antigravity CLI)
├── plugin.json                        # Antigravity plugin manifest
└── docs/                              # Setup guides per tool

Why Agent Skills?

AI coding agents default to the shortest path - which often means skipping specs, tests, security reviews, and the practices that make software reliable. Agent Skills gives agents structured workflows that enforce the same discipline senior engineers bring to production code.

Each skill encodes hard-won engineering judgment: when to write a spec, what to test, how to review, and when to ship. These aren't generic prompts - they're the kind of opinionated, process-driven workflows that separate production-quality work from prototype-quality work.

Skills bake in best practices from Google's engineering culture — including concepts from Software Engineering at Google and Google's engineering practices guide. You'll find Hyrum's Law in API design, the Beyonce Rule and test pyramid in testing, change sizing and review speed norms in code review, Chesterton's Fence in simplification, trunk-based development in git workflow, Shift Left and feature flags in CI/CD, and a dedicated deprecation skill treating code as a liability. These aren't abstract principles — they're embedded directly into the step-by-step workflows agents follow.

How it compares

Wondering how this stacks up against Superpowers or Matt Pocock's skills? See docs/comparison.md for an honest, side-by-side look at how the three are shaped differently and when to reach for each — including a link to a controlled head-to-head experiment.

Contributing

Skills should be specific (actionable steps, not vague advice), verifiable (clear exit criteria with evidence requirements), battle-tested (based on real workflows), and minimal (only what's needed to guide the agent).

See docs/skill-anatomy.md for the format specification and CONTRIBUTING.md for guidelines.

Team

agent-skills is built and maintained by:

Name	GitHub	Role
Addy Osmani	@addyosmani	Creator
Federico Bartoli	@federicobartoli	Collaborator
Joan León	@nucliweb	Collaborator

License

MIT - use these skills in your projects, teams, and tools.

chr0nzz/traefik-manager

A clean, self-hosted web UI for managing your Traefik reverse proxy.

Traefik Manager

A clean, self-hosted web UI for managing your Traefik reverse proxy.

Add routes, manage middlewares, monitor services, and view TLS certificates - all without touching a YAML file by hand.

_{Built for homelabbers who love Traefik but hate editing YAML at 2am.}

Highlights

Routes - add, edit, clone, and enable/disable HTTP, TCP, and UDP routes from the browser
Load balancing - multiple backends per route, sticky sessions, health checks, and router priority
Middlewares - 24 guided wizards plus a raw YAML editor, for HTTP and TCP
Multi-server - manage unlimited remote Traefik instances through a lightweight Go agent
Static config editor - edit the full traefik.yml from the UI and apply it with a one-click Traefik restart
Backups - timestamped local backups plus git push with history, diffs, and one-click restore
Monitoring - live services, certificates, access logs, CrowdSec, and CVE advisory warnings
Mobile app - Android companion app on Google Play

Quick Start

One-liner installer - installs Traefik + Traefik Manager together, or Traefik Manager on its own via Docker or a native Linux service:

curl -fsSL https://get-traefik.xyzlab.dev | bash

Manual Docker Compose:

services:
  traefik-manager:
    image: ghcr.io/chr0nzz/traefik-manager:latest
    container_name: traefik-manager
    restart: unless-stopped
    ports:
      - "5000:5000"
    environment:
      - COOKIE_SECURE=false
    volumes:
      - /path/to/traefik/dynamic.yml:/app/config/dynamic.yml
      - /path/to/traefik-manager/config:/app/config
      - /path/to/traefik-manager/backups:/app/backups

docker compose up -d

Open http://your-server:5000 - the setup wizard will guide you through the rest.

Screenshots

Features

Routes

Add, edit, clone, delete, and enable/disable HTTP, TCP, and UDP routes
Multiple domains per route with a chip builder, or switch to the advanced rule editor for complex expressions (PathPrefix, HostRegexp, && / ||)
Multiple backends per route - point HTTP, TCP, or UDP at several servers and let Traefik load-balance across them; route cards show a +N badge
Sticky sessions, health checks, and router priority - loadBalancer.sticky.cookie, loadBalancer.healthCheck, and router.priority as form fields instead of raw YAML
Guided route presets - one-click security headers and streaming tuning for Jellyfin/Emby/Plex; the middlewares they generate stay visible and editable, and hand-written ones are never overwritten
Per-route certificate resolver - pick any configured resolver, request wildcard certificates, or disable TLS
TLS options profiles - create named tls.options (min/max version, ciphers, mTLS, SNI strict) and assign them per route
insecureSkipVerify per service for backends with self-signed certs (Proxmox, Kasm, etc.)
Multi-config file support - mount several dynamic files via CONFIG_DIR / CONFIG_PATHS, choose the target file per route, create new files from the UI
Optional app icons on route cards and lists, shared with the Dashboard tab

Middlewares

24 guided wizards: Basic/Digest Auth, Forward Auth (with Authentik, Authelia, and Gatekeeper presets), OIDC Auth, Rate Limit, In-Flight Requests, IP Allowlist, Secure Headers, CORS, Redirects, Strip/Add/Replace Prefix, Retry, Circuit Breaker, Buffering, Compress, Chain, Encoded Characters, and more
Raw YAML editor for anything the wizards don't cover
Client IP source selector in the IP Allowlist wizard - match the real client instead of your proxy, via trusted hop depth (ipStrategy.depth) or excluded proxy IPs (ipStrategy.excludedIPs)
TCP middlewares alongside HTTP
Provider middlewares (Docker, Kubernetes, etc.) shown read-only in the provider tabs

Live Dashboard & Monitoring

Real-time stats: router counts, service health, entrypoints, Traefik version
Provider tabs: Docker, Kubernetes, Swarm, Nomad, ECS, Consul Catalog, Redis, etcd, Consul KV, ZooKeeper, HTTP, File - all API-based, no extra mounts
Traefik CVE advisory warnings - flags known security advisories affecting your running Traefik version
Optional tabs (toggle in Settings) - API-based, no mounts:
- Dashboard - routes grouped by category with app icons from selfh.st/icons (cached locally), per-card name/icon/group overrides
- Route Map - entry points, routes, middlewares, and services in a visual topology
- TLS Options - create and manage named tls.options profiles, assignable per route
- CrowdSec - decisions and alerts from a LAPI; ban, captcha, bypass, or unban IPs with one click
IP geolocation (optional, off by default) - country flags and a shaded, clickable world map of where your traffic and bans come from, on the Logs and CrowdSec tabs; lookups run on the server against a local DB-IP database (no IPs leave your machine), or point GEOIP_DB_PATH at your own MaxMind .mmdb
Optional tabs that read a mounted file:
- Certs (mount acme.json) - TLS certificates with expiry tracking; accepts several storage files or a directory, one per cert resolver
- Plugins (mount traefik.yml) - view plugins declared in your static config, and install new ones by pasting the snippet from the plugin catalog - TM writes the static config, optionally creates the matching middleware, and prompts a restart
- Logs (mount the Traefik access log) - parsed access log cards with full-detail panel
Client IP Diagnostic - a read-only tool in the top nav showing what this instance actually sees for your own request: the trusted client IP (the one that feeds the login and audit log, ipAllowList, and CrowdSec), the raw socket peer, the trusted proxy hop count, and the forwarding headers as received. Warns when the trusted IP is private, loopback, or CGNAT while you expect public clients
Source-IP classification in the Logs tab - every IP in Top IPs is tagged Public, Private, CGNAT, Loopback, or Link-local, so local noise like a gateway's hairpin-NAT address is easy to tell apart from real traffic
Configurable file paths - set the acme.json, access log, and static config paths from Settings → File Paths without a container restart; UI settings override env vars
Light, dark, or system theme - the nav-bar toggle sets the default for the whole instance, including the login page
Card/list view toggle on Routes, Middlewares, and Services

Static Config Editor (optional - mount `traefik.yml` read-write)

Edit every part of traefik.yml from the UI - Entrypoints, Cert Resolvers, Plugins, API, Logging, and Providers sections, plus a raw Monaco YAML editor for the full file
Changes are staged and backed up; apply them with a one-click Traefik restart - via socket proxy (recommended), poison pill (no socket needed), or direct socket
Full-screen reconnect overlay polls until Traefik is back up

Backups

Timestamped backups before every change, one-click restore, configurable retention
Git repository backup - auto-push your config to GitHub, Gitea, Forgejo, GitLab, or any HTTPS remote; browse commit history, view side-by-side diffs, restore any commit, set custom commit messages
One repository for all servers - agents can push to the Host's repository on their own branch, one branch per server (enforced), with per-agent history, diffs, and restore

Multi-Server (Agents)

Traefik Manager Agent (TMA) - a lightweight Go daemon that runs next to Traefik on any remote server
Server switcher in the nav bar - every tab (routes, services, middlewares, backups, logs) works against the active server
Setup wizard generates a ready-to-paste Docker Compose or Docker Run command; API key shown once and stored encrypted
Cert resolvers without mounting the static config - resolvers already in use by that server's routes are detected from its Traefik API, merged with its static config when mounted, plus an optional per-agent override field
Git backup without agent-side setup - enable Use Host Repository and the Host pushes that agent's config to its git repo on a dedicated branch; or run agents autonomously via GIT_BACKUP_* env vars
Manage unlimited servers from one TM - no VPN or SSH required

Notifications

In-app notification center for logins, config saves, restarts, backups, and CrowdSec actions
Webhook forwarding to Discord, Slack, ntfy, or any generic JSON endpoint, with a test button in Settings

Security

bcrypt passwords (cost 12), optional TOTP 2FA, session fixation protection, configurable inactivity timeout
OIDC / SSO - Keycloak, Google, Authentik, or any OIDC provider; restrict by email or group; can run as the sole login method with built-in auth disabled
Per-device API keys (up to 10, individually revocable) - the mobile app keeps working in every auth mode
CSRF protection, rate limiting, SSRF and git-transport hardening, secrets encrypted at rest (Fernet), atomic config writes
Configurable trusted proxy hops - PROXY_FIX_HOPS (default 1) sets how many reverse-proxy hops to trust when reading X-Forwarded-For, so the login and audit log record the real client behind a chain like Cloudflare → Traefik → TM. Only count hops you actually control - each trusted hop is one more entry a client could forge
See the security and Traefik hardening docs

Deployment

Runtime	Guide
Installer	One-liner: full stack, TM-only Docker, TM-only Linux service, Agent
Docker	Docker Compose setup, networking, behind Traefik
Podman	Rootless, Quadlet/systemd, SELinux labels
Linux	Native Python + systemd, no container required
Unraid	Community Applications template, networking, multi-config
Agent	TMA - remote agent for multi-server management

Documentation

Full documentation at traefik-manager.xyzlab.dev


Get Started	Deployment guides for Docker, Podman, and Linux
Traefik Stack	One-liner installer guide
Configuration	`manager.yml` reference
Environment Variables	`CONFIG_DIR`, `CONFIG_PATHS`, auth, domains, and more
Security	API keys, sessions, CSRF, rate limits, and hardening
Traefik Hardening	CVE advisories, header aliases, forwardAuth limits
API Reference	REST API for integrations and the mobile app
Agent API	TMA endpoints, auth, and health checks
Static Config Editor	Entrypoints, cert resolvers, and the restart flow
IP Geolocation	Country flags, world map, and bring-your-own database
Notification Webhooks	Discord, Slack, ntfy, and generic JSON payloads
OIDC / SSO	OIDC setup, provider examples, and access control
Git Repository Backup	Auto-push, commit history, diff viewer, and one-click restore
Mobile App	Android companion app setup and features
Reset Password	CLI reset, TOTP recovery, manual reset
UI Examples	Screenshots and walkthroughs
Provider Tabs	Docker, Kubernetes, Swarm, Nomad, ECS, and more

Mobile App

traefik-manager-mobile is a React Native companion app for managing Traefik Manager from your phone. Requires Traefik Manager v1.0.0 or higher.


Repo	github.com/chr0nzz/traefik-manager-mobile
Download	Latest release
Auth	Per-device API key - generate one in Settings → Authentication → App / Mobile API Keys

Features: browse routes, middlewares, and services · enable/disable routes · add and edit routes and middlewares with guided wizards · multiple domains per route · per-service insecureSkipVerify · multi-config file picker · edit mode for bulk actions · CrowdSec tab · system light/dark theme.

Tech Stack

Layer	Technology
Backend	Python 3.11 · Flask 3.1 · Gunicorn
Agent	Go 1.23 · Alpine Linux (TMA - remote agent daemon)
Config	ruamel.yaml (preserves comments and Go templates)
Auth	bcrypt · pyotp (TOTP) · Flask sessions · CSRF · Flask-Limiter · Fernet
Frontend	Vanilla JS · Tailwind CSS 3.4 · Phosphor Icons
Editor	Monaco Editor 0.52 (VS Code engine)
Route Map	dagre 0.8 (graph layout)
Geolocation	maxminddb · DB-IP Lite (local lookups, no external calls)
Tests	pytest · pyflakes · `go test` - run on every pull request
Container	Docker · Alpine Linux · all JS/CSS dependencies bundled at build time (no CDN at runtime)

Contributing

Pull requests are welcome. See CONTRIBUTING.md for how to report bugs, suggest features, and run the project locally.

Contributors

Traefik Manager is better because of the people who took the time to dig into it and send patches. Thank you.

Thanks as well to everyone who has opened an issue or a discussion. Several features started as a question from someone running into something unexpected, and the detail in those reports is what made them fixable.

License

GPL-3.0

santifer/career-ops

Open-source AI job search: scan job portals, evaluate listings with a structured A-F rubric into a 1.0-5.0 score, tailor your CV, track applications — runs locally in your AI coding CLI (Claude Code, Codex, OpenCode, Antigravity…)

I spent months applying to jobs the hard way. So I engineered the system I wish I had.
Companies use AI to filter candidates. I just gave candidates AI to choose companies.
Now it's open source.

_{FEATURED IN}

740+ job listings evaluated · 100+ personalized CVs · 1 dream role landed

_{Also runs on any agent-skill-standard CLI. See Supported CLIs.}

What Is This

career-ops (career-ops.org, also known as careerops) turns any AI coding CLI into a full job search command center. Instead of manually tracking applications in a spreadsheet, you get an AI-powered pipeline that:

Evaluates offers with a structured evaluation -- blocks A-F scored across 5 weighted dimensions, plus block G, a separate posting-legitimacy assessment that never affects the 1-5 score
Generates tailored PDFs -- ATS-optimized CVs customized per job description
Scans portals automatically (Greenhouse, Ashby, Lever, company pages)
Processes in batch -- evaluate 10+ offers in parallel with sub-agents
Tracks everything in a single source of truth with integrity checks
Researches companies and finds the right person to contact -- applications get you in the queue; research gets you a conversation

Important: This is NOT a spray-and-pray tool. career-ops is a filter -- it helps you find the few offers worth your time out of hundreds. The system strongly recommends against applying to anything scoring below 4.0/5. Your time is valuable, and so is the recruiter's. Always review before submitting.

career-ops is agentic: whichever AI coding CLI you choose navigates career pages with Playwright, evaluates fit by reasoning about your CV vs the job description (not keyword matching), and adapts your resume per listing.

Heads up: the first evaluations won't be great. The system doesn't know you yet. Feed it context -- your CV, your career story, your proof points, your preferences, what you're good at, what you want to avoid. The more you nurture it, the better it gets. Think of it as onboarding a new recruiter: the first week they need to learn about you, then they become invaluable.

Built by someone who used it to evaluate 740+ job offers, generate 100+ tailored CVs, and land a Head of Applied AI role. Read the full case study.

The CareerOps Manifesto

career-ops is the first reference implementation of the CareerOps Manifesto. read it. if it says what you believe, sign it. your signature becomes a commit.

Features

Feature	Description
Auto-Pipeline	Paste a URL, get a full evaluation + PDF + tracker entry
A-G Evaluation	Role summary, CV match, level strategy, comp research, personalization, interview prep (STAR+R) -- plus a Block G posting-legitimacy check that flags scams and ghost jobs, and a Work-Auth signal that flags an explicit no-sponsorship JD as a hard blocker
Interview Story Bank	Accumulates STAR+Reflection stories across evaluations -- 5-10 master stories that answer any behavioral question
Negotiation Scripts	Salary negotiation frameworks, geographic discount pushback, competing offer leverage
ATS PDF Generation	Keyword-injected CVs with Space Grotesk + DM Sans design
Cover Letter Generator	Research-backed cover letters with keyword mirroring, four interactive angle prompts (why/problems/approach/tone), draft-in-chat approval gate, and A4 PDF via the same HTML + Playwright pipeline as CVs. Auto-drafts on every evaluation; complete and generate on demand via `/career-ops cover`
Application Email Drafts	Formal recruiter/referral/cold application emails from a report or pasted JD, with subject line, attachment checklist, source-backed fit points, and a profile-driven contact block. Draft-only -- career-ops never sends, submits, or clicks anything.
Portal Scanner	100+ companies pre-configured (Anthropic, OpenAI, ElevenLabs, Retool, n8n...) + custom queries across Ashby, Greenhouse, Lever, Wellfound
Funded Company Discovery	Review-first `company:funded` command surfaces recently funded companies and source diagnostics from structured public feeds without editing your data
Batch Processing	Parallel evaluation with headless CLI workers (`claude -p` / `opencode run`)
Dashboard TUI	Terminal UI to browse, filter, and sort your pipeline
Human-in-the-Loop	AI evaluates and recommends, you decide and act. The system never submits an application -- you always have the final call
Pipeline Integrity	Automated merge, dedup, status normalization, health checks
Interview Suite	Time-blocked prep plans, practice sessions with feedback, post-interview debriefs (`interview/`), and a company red-flag detector (`interview-redflag`)
Offer Stage	Contract reading companion -- clause walk plus a lawyer question list (`offer-prep`) -- and a desired/advertised/actual salary-gap analyzer (`salary-gap.mjs`)
Follow-ups & Replies	Follow-up cadence calculator and seeded reminders (`followup-cadence.mjs`, `followup-seed.mjs`); employer reply classification into tracker updates (`reply-watch`)
Pattern Analysis	Rejection patterns and per-ATS-channel advance rates (`analyze-patterns.mjs`), lifetime funnel stats (`stats.mjs`), repost/ghost-job detection (`detect-reposts.mjs`)
Plugin System	Opt-in integrations (Gmail, Notion, Apify + a community registry), disabled by default -- see docs/PLUGINS.md
Beyond the CV	Company research (`deep`) surfaces AI strategy, recent moves, engineering culture, and the angle your profile should take. Contact discovery (`contacto`) identifies the hiring manager, recruiter, or team peer worth reaching out to and drafts a ≤300-character LinkedIn message tuned to each contact type. Formal application email drafts (`email`) turn an evaluated report or pasted JD into a subject line, body, and attachment checklist without sending, submitting, or clicking anything. Applications get you in the queue; research gets you a conversation.

Quick Start

Fastest way — one command:

npx @santifer/career-ops init

💡 npx ships with Node.js — it runs the installer once, without installing anything globally. No Node yet? Install it first. (Already using a Claude Code / Gemini / Codex CLI? Then you already have it.)

This clones the latest release into ./career-ops and installs dependencies. Then:

cd career-ops
claude   # or codex / qwen / opencode / agy / grok — open your AI CLI here

On first launch, career-ops walks you through setup — your CV, profile and target roles — just by chatting. Nothing to edit by hand.

Prefer to set it up manually? (git clone)

git clone https://github.com/santifer/career-ops.git
cd career-ops && npm install
npx playwright install chromium   # only needed for PDF generation

# 2. Check setup
npm run doctor                     # Validates all prerequisites

# 3. Configure
cp config/profile.example.yml config/profile.yml  # Edit with your details
cp templates/portals.example.yml portals.yml       # Customize companies

# 4. Add your CV
# Create cv.md in the project root with your CV in markdown

# 5. Open your AI CLI in this directory
claude   # or codex / opencode / qwen / agy / grok

# Then ask your CLI to adapt the system to you:
# "Change the archetypes to backend engineering roles"
# "Translate the modes to English"
# "Add these 5 companies to portals.yml"
# "Update my profile with this CV I'm pasting"

# 6. Start using
# Paste a job URL or JD text to trigger auto-pipeline
# If your CLI supports slash commands, use /career-ops (or its CLI-specific alias)
# In Codex, ask for the same mode in plain language, e.g.:
# "Run the career-ops scan mode"
# "Run the career-ops pipeline mode for data/pipeline.md"
# "Run the career-ops pdf mode for the latest evaluated role"
# "Run the career-ops tracker mode and summarize the current statuses"

Global install

npm i -g @santifer/career-ops

This installs the career-ops binary globally so you can run it directly instead of via npx. Unlike npx @santifer/career-ops init (which bootstraps a project directory), the global install gives you a persistent career-ops command available anywhere in your terminal.

Which one should you use?

npx @santifer/career-ops init — best for first use; creates a dedicated project folder.
npm i -g @santifer/career-ops — best once you have a project folder and want to run career-ops commands directly.

The system is designed to be customized by your AI coding CLI itself. Modes, archetypes, scoring weights, negotiation scripts -- just ask it to change them. It reads the same files it uses, so it knows exactly what to edit.

See docs/SETUP.md for the full setup guide, docs/RUNNING_ON_A_BUDGET.md for instructions on running career-ops cheaply using custom or local models (and docs/FREE_TIER.md for running it at zero cost on Antigravity CLI's free tier), docs/AUTOMATION.md for scheduling recurring scans and a zero-token triage-to-shortlist recipe, docs/APPLY_AUTOFILL.md for details on the ATS auto-fill flow, and docs/FAQ.md for answers to common setup questions. Design principles live in ARCHITECTURE.md; runtime flows in docs/ARCHITECTURE.md.

Antigravity CLI Integration

career-ops supports Antigravity CLI natively, the same way it supports Claude Code and OpenCode. All slash commands are available through the shared skill entrypoint, using the same modes/*.md evaluation logic.

Google has transitioned consumer Gemini CLI access to Antigravity CLI. GEMINI.md is now a no-op compatibility guard so Antigravity does not duplicate the full project instructions when it reads both AGENTS.md and GEMINI.md.

Native Antigravity CLI

# 1. Run in the career-ops directory
cd career-ops
agy

# 2. Use the unified /career-ops command with subcommands:
/career-ops "Senior AI Engineer at Anthropic..."
/career-ops pipeline
/career-ops scan
/career-ops pdf
/career-ops tracker

The skill is defined using the open standard in .agents/skills/career-ops/SKILL.md and symlinked/referenced for each supported CLI (e.g. .claude/, .cursor/, .qwen/, .antigravitycli/, .grok/).

Codex Integration

career-ops supports Codex through the same shared router, but the invocation model is different from CLIs that auto-register slash commands. For the full guide, see docs/CODEX.md.

Interactive Codex

cd career-ops
codex

Slash commands are not guaranteed in Codex. If /career-ops is unavailable, ask Codex to run the mode directly in plain language:

Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123
Run the career-ops scan mode and summarize new matches.
Run the career-ops pipeline mode for data/pipeline.md.
Run the career-ops pdf mode for the latest evaluated role.
Run the career-ops tracker mode and summarize the current statuses.

One-shot Codex (`codex exec`)

codex exec "Evaluate this JD with career-ops auto-pipeline: https://company.com/jobs/123"
codex exec "Run career-ops scan mode in this repo and summarize new matches."
codex exec "Run career-ops pipeline mode for data/pipeline.md."
codex exec "Run career-ops pdf mode for the latest evaluated role."
codex exec "Run career-ops tracker mode and summarize the current statuses."

Grok Build CLI Integration

career-ops supports Grok Build CLI natively, the same way it supports Claude Code and OpenCode. AGENTS.md is auto-loaded as project rules, and all slash commands are available through the shared skill entrypoint.

Native Grok Build CLI

# 1. Run in the career-ops directory
cd career-ops
grok

# 2. Use the unified /career-ops command with subcommands:
/career-ops "Senior AI Engineer at Anthropic..."
/career-ops pipeline
/career-ops scan
/career-ops pdf
/career-ops tracker

For headless batch workers, use grok -p "prompt" (add --yolo to auto-approve tool executions).

Standalone Gemini API Script (No CLI install needed)

# 1. Get a free API key at https://aistudio.google.com/apikey
cp .env.example .env
# Edit .env, set GEMINI_API_KEY=your_key_here

# 2. Install dependencies
npm install

# 3. Evaluate a job description
node gemini-eval.mjs "We are looking for a Senior AI Engineer..."
node gemini-eval.mjs --file ./jds/my-job.txt
node agent-inbox.mjs add "..."   # queue a request for the next session
npm run gemini:eval -- "JD text here"

Free tier: Both options work without billing. Native CLI uses Google OAuth; the API script uses gemini-3.6-flash (rate limits are model- and tier-dependent; see Google AI docs for current quotas).

Usage

career-ops uses a shared command router. In CLIs that register slash commands, it looks like this:

/career-ops                → Show all available commands
/career-ops {paste a JD}   → Full auto-pipeline (evaluate + PDF + tracker)
/career-ops scan           → Scan portals for new offers
/career-ops pdf            → Generate ATS-optimized CV
/career-ops cover          → Cover letter generator (paste JD or /career-ops cover {slug})
/career-ops email          → Formal application email draft (draft-only; never sends, submits, or clicks)
/career-ops batch          → Batch evaluate multiple offers
/career-ops tracker        → View application status
/career-ops apply          → Fill application forms with AI
/career-ops outcome        → Record application outcome & archive artifacts
/career-ops pipeline       → Process pending URLs
/career-ops contacto       → Find hiring manager / recruiter / peer + draft a ≤300-char LinkedIn message per contact type
/career-ops deep           → Generate a structured 6-axis research prompt (AI strategy, recent moves, culture, challenges, competitors, candidate angle)
/career-ops training       → Evaluate a course/cert
/career-ops project        → Evaluate a portfolio project

Or just paste a job URL or description directly -- career-ops auto-detects it and runs the full pipeline.

In Codex, slash commands are not guaranteed. Use the same mode names in a prompt instead, or call them from codex exec.

How It Works

You paste a job URL or description
        │
        ▼
┌──────────────────┐
│  Archetype       │  Classifies: LLMOps / Agentic / PM / SA / FDE / Transformation
│  Detection       │
└────────┬─────────┘
         │
┌────────▼─────────┐
│  A-G Evaluation  │  Match, gaps, comp research, STAR stories, legitimacy
│  (reads cv.md)   │
└────────┬─────────┘
         │
    ┌────┼────┐
    ▼    ▼    ▼
 Report  PDF  Tracker
  .md   .pdf  entry

Pre-configured Portals

The scanner comes with 100+ companies ready to scan and 45+ search queries across major job boards. Copy templates/portals.example.yml to portals.yml and add your own:

AI Labs: Anthropic, OpenAI, Mistral, Cohere, LangChain, Pinecone Voice AI: ElevenLabs, PolyAI, Parloa, Hume AI, Deepgram, Vapi, Bland AI AI Platforms: Retool, Airtable, Vercel, Temporal, Glean, Arize AI Contact Center: Ada, LivePerson, Sierra, Decagon, Talkdesk, Genesys Enterprise: Salesforce, Twilio, Gong, Dialpad LLMOps: Langfuse, Weights & Biases, Lindy, Cognigy, Speechmatics Automation: n8n, Zapier, Make.com European: Factorial, Attio, Tinybird, Clarity AI, Travelperk

Job boards searched: 55+ provider modules cover ATS APIs, board-wide feeds, XML/RSS feeds, markdown feeds, and local parsers. See Supported job boards for the full table.

By default node scan.mjs (a.k.a. npm run scan) trusts what each ATS feed returns. Some companies leave stale postings in their public API even after the role is closed, so those expired entries can leak into pipeline.md. Pass --verify to launch Playwright after the API pass and drop expired postings before they hit the pipeline:

node scan.mjs --verify          # zero-token discovery + Playwright liveness check

The verification is sequential and only runs against new offers (after dedup), so the cost stays bounded.

Dashboard TUI

The built-in terminal dashboard lets you browse your pipeline visually:

npm run serve:dashboard   # launch the TUI
npm run build:dashboard   # optional: build the standalone binary

Features: 6 filter tabs, 4 sort modes, grouped/flat view, lazy-loaded previews, inline status changes.

There is also an experimental web UI (alpha, opt-in — nothing runs unless you start it): see web/README.md.

Project Structure

career-ops/
├── AGENTS.md                    # Canonical agent instructions (all CLIs)
├── CLAUDE.md                    # Claude Code wrapper (imports AGENTS.md)
├── CODEX.md                     # Codex wrapper (imports AGENTS.md)
├── OPENCODE.md                  # OpenCode wrapper (imports AGENTS.md)
├── GEMINI.md                    # Legacy no-op guard to avoid Antigravity duplicate context
├── cv.md                        # Your CV (create this)
├── article-digest.md            # Your proof points (optional)
├── config/
│   └── profile.example.yml      # Template for your profile
├── modes/                       # Skill modes
│   ├── _shared.md               # Shared context (customize this)
│   ├── oferta.md                # Single evaluation
│   ├── pdf.md                   # PDF generation
│   ├── cover.md                 # Cover letter generation
│   ├── email.md                 # Formal application email drafts
│   ├── scan.md                  # Portal scanner
│   ├── batch.md                 # Batch processing
│   └── ...
├── templates/
│   ├── cv-template.html         # ATS-optimized CV template
│   ├── portals.example.yml      # Scanner config template
│   └── states.yml               # Canonical statuses
├── batch/
│   ├── batch-prompt.md          # Self-contained worker prompt
│   └── batch-runner.sh          # Orchestrator script
├── dashboard/                   # Go TUI pipeline viewer
├── data/                        # Your tracking data (gitignored)
├── reports/                     # Evaluation reports (gitignored)
├── output/                      # Generated PDFs (gitignored)
├── fonts/                       # Space Grotesk + DM Sans
├── docs/                        # Setup, customization, budget guide, architecture
└── examples/                    # Sample CV, report, proof points

Tech Stack

Agent: AI coding CLI with shared skills and modes (AGENTS.md + CLI wrapper)
PDF: Playwright + HTML template
Cover letters: HTML template + Playwright (A4 PDF, same pipeline as CVs)
Scanner: Playwright + Greenhouse API + WebSearch
Dashboard: Go + Bubble Tea + Lipgloss (Catppuccin Mocha theme)
Data: Markdown tables + YAML config + TSV batch files

Also Open Source

cv-santiago -- The portfolio website (santifer.io) with AI chatbot, LLMOps dashboard, and case studies. If you need a portfolio to showcase alongside your job search, fork it and make it yours.

FAQ

What is career-ops? career-ops is an open-source, CLI-agnostic job-search command center. It turns any AI coding CLI into a pipeline that evaluates job offers against your CV, generates ATS-tailored PDFs, finds the right person to contact, and tracks everything in one place — while you keep the final decision. It is the first reference implementation of the CareerOps Manifesto. More at career-ops.org.

Can I run career-ops for free, or on a cheaper / local model? Yes. career-ops is CLI-agnostic and runs on free and local models — via OpenRouter free models, Ollama, or any OpenAI-compatible endpoint — so you are not tied to a paid subscription. See docs/RUNNING_ON_A_BUDGET.md for the full setup.

I pay for Claude Pro/Max but career-ops is burning API credits. Why? Because an ANTHROPIC_API_KEY in your environment takes precedence over your logged-in subscription: the CLI uses the key and bills per token. Run echo $ANTHROPIC_API_KEY, and if it prints anything, remove it from your shell profile, restart the terminal and run /login. Batch mode is the exception, since claude -p workers do not use the interactive login: run claude setup-token once and export the result as CLAUDE_CODE_OAUTH_TOKEN. Full walkthrough in docs/RUNNING_ON_A_BUDGET.md.

Which AI CLIs does career-ops work with? career-ops runs on any major AI coding CLI — Claude Code, Codex, Gemini / Antigravity, OpenCode, Grok, Qwen and more — through the open Agent Skill Standard, so it is never locked to a single vendor. Use the CLI you already have.

How do I install career-ops on Windows? career-ops runs on Windows. If skills fail to load with a symlink error during install, the fix is in docs/FAQ.md. Full steps are in docs/SETUP.md.

Does career-ops auto-apply to jobs for me? No. career-ops is a filter, not a spray-and-pray auto-applier. The AI evaluates, ranks and drafts; you review and decide. It never submits, sends, or clicks anything — you always have the final call. That human-in-the-loop design is the whole point.

Is career-ops free and open source? Yes. career-ops is free and open source, and for the candidate it always will be — it is the first reference implementation of the CareerOps Manifesto. Read it, and if it says what you believe, sign it.

About the Author

I'm Santiago Fernández de Valderrama Aparicio (santifer) -- Head of Applied AI, former founder (built and sold a business that still runs with my name on it). I built career-ops to manage my own job search. It worked: I used it to land my current role.

Curious how this repo is maintained in ~4 hours a week? Read Agentic maintenance: how career-ops is run by a fleet of AI agents.

My portfolio and other open source projects → santifer.io

Wikidata: Santiago Fernández de Valderrama Aparicio · career-ops.

Disclaimer

career-ops is a local, open-source tool, NOT a hosted service. By using this software, you acknowledge:

You control your data. Your CV, contact info, and personal data stay on your machine and are sent directly to the AI provider you choose (Anthropic, OpenAI, etc.). We do not collect, store, or have access to any of your data.
You control the AI. The default prompts instruct the AI not to auto-submit applications, but AI models can behave unpredictably. If you modify the prompts or use different models, you do so at your own risk. Always review AI-generated content for accuracy before submitting.
You comply with third-party ToS. You must use this tool in accordance with the Terms of Service of the career portals you interact with (Greenhouse, Lever, Workday, LinkedIn, etc.). Do not use this tool to spam employers or overwhelm ATS systems.
No guarantees. Evaluations are recommendations, not truth. AI models may hallucinate skills or experience. The authors are not liable for employment outcomes, rejected applications, account restrictions, or any other consequences.

See LEGAL_DISCLAIMER.md for full details. This software is provided under the MIT License "as is", without warranty of any kind.

Contributors

Every person who has shipped code, docs, translations or tests is listed in CONTRIBUTORS.md — including non-code contributions, which the graph above cannot show.

Got hired using career-ops? Share your story!

License & Trademark

The code is licensed under MIT. The "career-ops" name and brand are governed by the Trademark Policy, permissive for community use, reserved for commercial product naming and endorsement.

Let's Connect

techjarves/Uncensored-Local-Studio

Uncensored local AI studio for Windows, Linux, and macOS. Zero-setup GUI for Image Generation, GGUF LLMs, Text to Speech & Speech to Text

Uncensored AI Studio

A premium, zero-configuration local AI studio and offline GUI for Stable Diffusion (Image Generation), LLMs (Chat), Whisper (Speech-to-Text), and Kokoro (Text-to-Speech). Powered by hardware-accelerated GPU and NPU execution on Windows, Linux, and macOS.

🎥 Watch the Setup & Demo Video: https://youtu.be/yeFvP3SWMak

📖 Table of Contents

📖 What is Uncensored AI Studio?

Uncensored AI Studio is a completely offline, zero-setup, self-contained AI studio for Windows, Linux, and macOS. Unlike cloud-based AI systems, it runs entirely on your own hardware with no censorship, tracking, subscriptions, or login requirements.

It unifies four major local AI capabilities into one high-performance desktop interface:

🎨 Image Generation (Stable Diffusion): Generate and edit high-quality images offline using .safetensors, .gguf, or .ckpt model weights.
💬 Text Chat (LLMs): Converse privately with open-source language models (GGUF format) powered by official, high-performance llama.cpp backends.
🎙️ Speech-to-Text (Whisper): Transcribe voice recordings and speech to text in real-time with an integrated whisper.cpp engine.
🗣️ Text-to-Speech (Kokoro TTS): Convert text outputs into highly natural, lifelike vocal audio offline using the Kokoro-82M ONNX model.

🌟 Key Features

100% Offline & Private: Run inferences locally. No internet, telemetry, cloud logging, or API keys required.
Zero-Install Portability: Entire runtime (Node.js, models, GPU backends) is self-contained. Zero global system environment changes.
Auto-Configured Acceleration: Auto-detects hardware specs to load CUDA (Nvidia), ROCm (AMD), Vulkan (Intel/AMD/NVIDIA), Metal (macOS), or OpenVINO (Intel NPU) backends.
Integrated Model Manager: Paste Hugging Face URLs to download weights directly, or drag-and-drop local weights to import them.
Live Performance Monitor: Track CPU, RAM, GPU, and VRAM utilization in real-time directly inside the web UI.
Local Output Gallery: Saves generated images side-by-side with prompt parameters and metadata JSON files.

⚙️ Workspace & Engine Architecture

To avoid exhausting system RAM or VRAM, text and image engines are mutually exclusive by default. You can switch between workspaces inside the UI:

Image Generation Workspace: Uses a dedicated stable-diffusion.cpp backend node. Model weights are stored in app/models/.
Text Chat Workspace: Uses a portable llama.cpp server backend. Model weights (.gguf) are stored in app/llm-models/. A small Qwen2.5 Coder starter model can be downloaded directly from the Text Chat panel.
Speech Worker (Whisper): Runs a localized whisper-cli process to convert your vocal input to text.
Audio Output (Kokoro TTS): Utilizes kokoro-js locally on the server side to read responses in natural voices.

Supported Models

The app is designed around single-file local models that can be loaded directly by the bundled backend engines.

Image generation

Model type	Supported	Put files in	Notes
Stable Diffusion 1.5 checkpoints	Yes	`app/models/`	Best compatibility. Use `.safetensors` or `.ckpt` files.
SDXL checkpoints	Yes	`app/models/`	Supported as single-file checkpoints. Requires more RAM/VRAM than SD 1.5.
Single-file SD/SDXL GGUF checkpoints	Limited	`app/models/`	Only complete single-file checkpoints are supported.
OpenVINO image model folders	Intel NPU only	`app/openvino-models/`	Download from the Model Manager after running the OpenVINO setup.
CoreML image models	Apple Silicon only	`app/models/`	Requires macOS on Apple Silicon and the CoreML setup path.
Flux, HiDream, Hunyuan, Wan, Qwen Image, Z-Image workflows	No	N/A	These usually require separate diffusion, VAE, and text encoder files and are not one-click checkpoint loads in this app.
LoRA, ControlNet, VAE-only, text-encoder-only, or diffusion-only files	No	N/A	Companion files are not loaded as standalone image models.

Known-good image models available from the Model Manager:

Name	Filename	Type	Approx. size	Recommended use
Juggernaut XL v9 Lightning	`Juggernaut_RunDiffusionPhoto2_Lightning_4Steps.safetensors`	SDXL	6.6 GB	High-quality photorealism on mid/high tier machines.
DreamShaper XL Lightning	`DreamShaperXL_Lightning.safetensors`	SDXL	6.6 GB	General SDXL images, fantasy, renders, and illustration.
DreamShaper 8	`DreamShaper_8_pruned.safetensors`	SD 1.5	2.1 GB	Faster, lower-memory image generation.
CyberRealistic V8	`CyberRealistic_V8_FP16.safetensors`	SD 1.5	2.0 GB	Realistic SD 1.5 images and lower-memory systems.
Rev Animated	`rev-animated-v1-2-2.safetensors`	SD 1.5	2.0 GB	Stylized/anime SD 1.5 images.
LCM DreamShaper OpenVINO	`OpenVINO/LCM_Dreamshaper_v7-fp16-ov`	OpenVINO	2.7 GB	Intel Core Ultra NPU test model.

Text, speech, and TTS

Workspace	Supported model files	Put files in	Notes
Text Chat	`.gguf` llama.cpp models	`app/llm-models/`	Use single-file GGUF chat/instruct models. Vision models may also require a matching `mmproj` file.
Speech-to-Text	whisper.cpp `.bin` models	`app/speech-models/`	Use Whisper GGML/whisper.cpp model files.
Text-to-Speech	Kokoro `.json` manifests and model assets	`app/tts-models/` / `app/tts-runtime/`	Use the built-in Kokoro setup and Model Manager entries.

Note

Linux release binaries are built for Ubuntu 24.04-era systems and require glibc 2.38+ plus GLIBCXX_3.4.32+. On older Ubuntu/Debian VMs, a model such as CyberRealistic may be valid but the backend can still fail before loading it. Upgrade the VM OS or build the backend from source.

📁 Folder Architecture

Uncensored-AI-Studio/
├── windows.bat                # Windows Launcher (Double-click entrypoint)
├── linux.sh                   # Linux Launcher (Terminal entrypoint)
├── mac.sh                     # macOS Launcher (Terminal entrypoint)
├── LICENSE                    # MIT Open Source License
├── .gitignore                 # Excludes models and output images from version control
├── README.md                  # Detailed system documentation
├── scripts/
│   ├── setup/                 # Platform setup and backend installers
│   ├── reset/                 # Clean install & environment repair
│   ├── server/                # UI web server and backend lifecycle manager
│   ├── workers/               # Local worker processes
│   ├── build/                 # Optional source build helpers
│   └── config/                # Runtime configuration catalogs
└── app/
    ├── frontend/              # UI source code (Vite + React)
    ├── models/                # Place image weights here (.safetensors, .gguf, .ckpt)
    ├── llm-models/            # Place text GGUF weights here
    └── outputs/               # Saved images and parameters metadata

🚀 Getting Started

Ensure you have a modern web browser installed. Follow the quick guide below for your platform:

Windows Setup

Launch: Double-click windows.bat.

Note

On the first run, the script will automatically download a portable Node.js runtime and configure pre-compiled GPU/CPU backend binaries.
Add Models: Drop .safetensors, .gguf, or .ckpt weights into app/models/ (or download them via the Model Manager tab in the UI).
Generate: Open http://localhost:1420 in your browser, select your model, and write a prompt.

Linux Setup

Make executable: Open a terminal in the project folder and make the script executable:
```
chmod +x linux.sh
```
Launch: Run ./linux.sh.
- NVIDIA GPU Users: You will be prompted to set up the high-performance CUDA backend (downloads prebuilt or automatically compiles from source as a fallback).
- AMD Radeon Performance: Run with ./linux.sh --max-perf to add the ROCm backend (~1.3 GB download).
- Intel Core Ultra NPU: Run with ./linux.sh --setup-openvino to configure Intel NPU support (requires Intel Linux NPU driver).
Add Models: Drop your weights into app/models/ or download them via the Model Manager tab.
Generate: Open http://localhost:1420 in your browser.

macOS Setup

Make executable: Open a terminal in the project folder and make the script executable:
```
chmod +x mac.sh
```
Launch: Run ./mac.sh.

Important

The prebuilt macOS backend is optimized for Apple Silicon (M1 or newer) and uses Metal GPU acceleration. (macOS Intel hardware is completely unsupported).
Add Models: Drop your weights into app/models/ or download them via the Model Manager tab.
Generate: Open http://localhost:1420 in your browser.

🖥️ Hardware Compatibility & Acceleration

Windows

GPU Vendor	Tech	Status	Notes
Nvidia	CUDA	✅ Native	Maps `sd-cuda.exe` with Nvidia SDK 12 optimizations.
AMD Radeon	Vulkan	✅ Native	Maps `sd-vulkan.exe` with Vulkan API acceleration.
Intel Arc	Vulkan	✅ Native	Maps `sd-vulkan.exe` for Intel hardware.
Integrated / None	CPU	⚠️ Fallback	Runs on logical CPU threads (slow).

Linux

GPU Vendor	Primary	Fallback	Notes
NVIDIA	CUDA / Vulkan	Vulkan / CPU	Auto-detects NVIDIA. Prompt-driven CUDA setup downloads prebuilt or compiles from source. Falls back to Vulkan for GTX.
AMD Radeon	ROCm	Vulkan	ROCm provides best AMD performance when host ROCm drivers are available.
Intel Arc / integrated	Vulkan	CPU	Cross-vendor Vulkan support.
Intel Core Ultra NPU	OpenVINO NPU	CPU	Requires the Intel Linux NPU driver, kernel 6.6+, Python 3, and `./linux.sh --setup-openvino`.
Integrated / None	CPU	—	Runs on logical CPU threads (slow).

macOS

Hardware	Primary	Fallback	Notes
Apple Silicon (M1 or newer)	Metal	CPU	Uses the official Darwin arm64 stable-diffusion.cpp backend.

Important

System Requirements & Notes:

64-bit Windows 10 or Windows 11 is required for the portable Node.js 22 runtime used by the Windows launcher.
glibc 2.38 or newer is required for the prebuilt Linux backends (Ubuntu 24.04, Fedora 40+, etc.). The setup script will warn you if your glibc is older.
Linux runtime libraries: The prebuilt backends require libgomp.so.1; Vulkan additionally requires libvulkan.so.1 and a working GPU driver. The setup script now checks these before installing a backend and prints the exact distro package command when one is missing.
Linux OpenVINO NPU: Intel Core Ultra, x86_64 Linux, kernel 6.6+, a working /dev/accel/accel0 device, Python 3 with venv, and the Intel Linux NPU driver are required.

🛠️ Troubleshooting & FAQ

Reset Environment: If a build fails or you want to clear dependencies

Run scripts/reset/reset.ps1 (Windows) or scripts/reset/reset.sh (Linux/macOS). This will clear temporary compilation and package caches to repair your environment. (Note: This preserves your model weights and generated output images).

Linux backends fail to start with GLIBC_2.38 not found

The prebuilt binaries require glibc 2.38+ (e.g. Ubuntu 24.04). If your distribution uses an older glibc version, you can upgrade your operating system or compile the backend from source (see the Building From Source guide below).

Port Conflicts: Default port address already busy

The web user interface runs on port 1420 by default. The GPU backend manager attempts to bind to port 8080 first, then automatically detects and falls back to a free system port if 8080 is already occupied.

Linux ROCm not loading for AMD Radeon GPUs

Ensure your AMD GPU hardware and host kernel are fully compatible with ROCm 7.13. If ROCm fails to initialize correctly, the application will automatically fall back to Vulkan acceleration.

Linux uses the integrated GPU instead of the discrete GPU

On dual-GPU Linux systems, Vulkan device order can put the integrated Intel GPU at vulkan0 and the discrete AMD/NVIDIA GPU at vulkan1. The launcher now tries to prefer a discrete Vulkan device when vulkaninfo --summary is available. To force a device manually, start the app with SD_VULKAN_DEVICE=vulkan1 ./linux.sh or use another index such as vulkan0/vulkan2.

Windows exits with code 3221225781 (0xC0000135)

This code means Windows could not locate a required backend DLL:

For AMD/Intel Vulkan: Update your GPU driver to one with full Vulkan runtime support, then rerun the setup script to restore app/backend/win/vulkan/.
For NVIDIA CUDA: Install or update your NVIDIA graphics driver, then rerun the setup script to restore the CUDA runtime DLLs.

Generation shows "server is not responding or crashed"

This indicates that the local backend engine process terminated. Check your launch terminal (where you executed windows.bat, ./linux.sh, or ./mac.sh) for the exact console error. Common causes include glibc version mismatches, missing Vulkan drivers, or system out-of-memory (OOM) issues.

🔨 Building From Source

The setup script (scripts/setup/setup.sh) now automates building and setting up the CUDA backend from source when selected. If you want to manually build all backends (CPU, Vulkan, and CUDA) at once, you can run the included scripts/build/build_from_source.sh script.

For macOS, the included scripts/build/build_from_source.sh builds the Metal backend and copies it to app/backend/mac/sd.

Requirements

git, cmake, make (or ninja), and a C++17 compiler (g++ / clang++).
For CUDA: the NVIDIA CUDA toolkit (nvcc) must be on your PATH.
For Vulkan: the Vulkan SDK / loader, a compatible driver, and glslc (Ubuntu/Debian package: glslc).
For ROCm: AMD ROCm development libraries.
For macOS Metal: Apple Command Line Tools or Xcode.

Build commands

# 1. Clone upstream
git clone https://github.com/leejet/stable-diffusion.cpp.git
cd stable-diffusion.cpp
mkdir build && cd build

# 2. Configure for your backend (pick ONE)
# CPU only
cmake .. -DSD_BUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release

# CUDA
cmake .. -DSD_CUDA=ON -DSD_BUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release

# Vulkan
cmake .. -DSD_VULKAN=ON -DSD_BUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release

# ROCm
cmake .. -DSD_HIPBLAS=ON -DSD_BUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release

# macOS Metal
cmake .. -DSD_METAL=ON -DSD_BUILD_SHARED_LIBS=ON -DCMAKE_BUILD_TYPE=Release

# 3. Build
cmake --build . --config Release -j$(getconf _NPROCESSORS_ONLN 2>/dev/null || sysctl -n hw.ncpu)

# 4. Copy the binaries into this project
cp bin/sd* /path/to/Uncensored-AI-Studio/app/backend/linux/<backend>/

After copying, rename the server binary to match what scripts/server/serve.cjs expects:

Vulkan: sd → sd-vulkan
ROCm: sd → sd-rocm

Then restart the app with ./linux.sh (Linux) or ./mac.sh (macOS).

📝 License

This project is licensed under the MIT License - see the LICENSE file. Bundles stable-diffusion.cpp (MIT License). Model weights are subject to their respective creators' licenses.

bmad-code-org/BMAD-METHOD

Breakthrough Method for Agile Ai Driven Development

Agile Ai Driven Development — turn an idea or change request into working software without giving up the thinking.

Ai Driven Development (AiDD) covers the whole effort, not only the code: what to build, how it holds together, and how it changes as you learn. BMad Method is the agile way to do it — decisions stay explicit, context carries forward, and the process sizes itself to the work. Small changes go straight to build. Complex work gets the depth it needs. The same method covers a weekend prototype and a system with years of history behind it.

Start anywhere. Use BMad end to end, or carry its briefs, specifications, and architecture into your existing delivery workflow.

Start Building

Prerequisites: Node.js 20.12+, Python 3.10+, and uv

npx bmad-method install

Open your project in your AI coding tool, invoke bmad-build with what you want to change, and keep making the decisions that matter. Run bmad-help whenever you want guidance on what comes next or what is optional.

Build your first project with BMad →

Add BMad to an existing codebase →

BMad is free and open source, with no paywalled workflows or gated community. For prerelease builds, CI/CD, configuration overrides, and non-interactive setup, see the installation guide.

Why BMad?

Coding assistants are effective at implementation, but they often turn unstated assumptions into code. BMad keeps you in control while its agents and workflows make the important decisions explicit and preserve them as context for the work that follows.

Right-sized process — Go directly to implementation for clear changes or add deeper planning for larger initiatives.
New or existing code — Start from nothing, or establish verified context on a codebase you inherited and work from what is actually there.
Durable context — Carry product and technical decisions forward instead of re-explaining them in every chat.
Specialized perspectives — Bring in product, architecture, UX, development, and testing expertise when it helps.
Guided collaboration — Use structured workflows and multiple-agent discussions without handing over judgment.
One delivery path — Move from early thinking through reviewed implementation, correction, and learning.

See how the workflows fit together →

BMad Ecosystem

Install the core method or add official modules for specialized work.

Module	Purpose
BMad Method	Plan and deliver software, from new prototypes to established codebases
BMad Builder	Skill, workflow, and agent builder
BMad Creative Intelligence Suite	Creative thinking partners for innovation, design thinking, and storytelling
BMad Test Architect	Enterprise testing add-on for BMad Method
BMad Loop	Builds, verifies, and retros a whole epic unattended
BMad Game Dev Studio	Ideate, design, and build games in any framework, including Unity, Unreal, Godot, and Phaser

Plan on the Web

Web bundles package selected BMad workflows as Google Gemini Gems and ChatGPT Custom GPTs. Use them for planning in your existing web subscription, then bring the resulting artifacts into your AI coding tool for implementation.

Documentation

Getting Started — Install BMad and build a small project.
Workflow Map — Understand the available paths and outputs.
Established Projects — Add BMad to an existing codebase.
Upgrade to V6 — Migrate from an earlier version.

Roadmap

See what is in progress and what is planned on the public roadmap.

Community

Discord — Get help, share ideas, and collaborate.
YouTube — Watch tutorials and master classes.
GitHub Issues — Report bugs and request features.
GitHub Discussions — Join longer community conversations.
BMad Code — Explore the wider ecosystem.

Support and Contributing

BMad is free for everyone and always will be. Star the repository, buy me a coffee, or email contact@bmadcode.com for corporate sponsorship.

Contributions are welcome. Read CONTRIBUTING.md before opening a pull request.

License

MIT License — see LICENSE for details.

BMad and BMAD-METHOD are trademarks of BMad Code, LLC. See TRADEMARK.md for details.

See CONTRIBUTORS.md for contributor information.

coreyhaines31/marketingskills

Marketing skills for Claude Code and AI agents. CRO, copywriting, SEO, analytics, and growth engineering.

Marketing Skills for AI Agents

A collection of AI agent skills focused on marketing tasks. Built for technical marketers and founders who want AI coding agents to help with conversion optimization, copywriting, SEO, analytics, and growth engineering. Works with Claude Code, OpenAI Codex, Cursor, Windsurf, and any agent that supports the Agent Skills spec.

Built by Corey Haines. Need hands-on help? Check out Conversion Factory — Corey's agency for conversion optimization, landing pages, and growth strategy. Want to learn more about marketing? Subscribe to Swipe Files. Want to get dangerously good at using AI for marketing? Check out AI Marketing Training. Want an autonomous AI agent that uses these skills to be your CMO? Try Magister.

New to the terminal and coding agents? Check out the companion guide Coding for Marketers.

Contributions welcome! Found a way to improve a skill or have a new one to add? Open a PR.

Run into a problem or have a question? Open an issue — we're happy to help.

What are Skills?

Skills are markdown files that give AI agents specialized knowledge and workflows for specific tasks. When you add these to your project, your agent can recognize when you're working on a marketing task and apply the right frameworks and best practices.

How Skills Work Together

Skills reference each other and build on shared context. The product-marketing skill is the foundation — every other skill checks it first to understand your product, audience, and positioning before doing anything.

                            ┌──────────────────────────────────────┐
                            │          product-marketing           │
                            │    (read by all other skills first)  │
                            └──────────────────┬───────────────────┘
                                               │
    ┌──────────────┬─────────────┬─────────────┼─────────────┬──────────────┬──────────────┐
    ▼              ▼             ▼             ▼             ▼              ▼              ▼
┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐ ┌──────────┐ ┌─────────────┐ ┌───────────┐
│  SEO &   │ │   CRO    │ │Content & │ │  Paid &    │ │ Growth & │ │  Sales &    │ │ Strategy  │
│ Content  │ │          │ │   Copy   │ │Measurement │ │Retention │ │    GTM      │ │           │
├──────────┤ ├──────────┤ ├──────────┤ ├────────────┤ ├──────────┤ ├─────────────┤ ├───────────┤
│seo-audit │ │cro       │ │copywritng│ │ads         │ │referrals │ │revops       │ │mktg-ideas │
│ai-seo    │ │signup    │ │copy-edit │ │ad-creative │ │free-tools│ │sales-enable │ │mktg-psych │
│site-arch │ │onboarding│ │cold-email│ │ab-testing  │ │churn-    │ │launch       │ │customer-  │
│programm  │ │popups    │ │emails    │ │analytics   │ │ prevent  │ │pricing      │ │ research  │
│schema    │ │paywalls  │ │social    │ │            │ │community │ │competitors  │ │           │
│content   │ │          │ │video     │ │            │ │lead-magnt│ │comp-profile │ │           │
│aso       │ │          │ │image     │ │            │ │co-mktg   │ │directory    │ │           │
│          │ │          │ │sms       │ │            │ │          │ │prospecting  │ │           │
└────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘ └────┬─────┘ └──────┬──────┘ └─────┬─────┘
     │            │            │              │             │              │              │
     └────────────┴─────┬──────┴──────────────┴─────────────┴──────────────┴──────────────┘
                        │
         Skills cross-reference each other:
           copywriting ↔ cro ↔ ab-testing
           revops ↔ sales-enablement ↔ cold-email
           seo-audit ↔ schema ↔ ai-seo
           customer-research → copywriting, cro, competitors

See each skill's Related Skills section for the full dependency map.

Available Skills

Skill	Description
ab-testing	When the user wants to plan, design, or implement an A/B test or experiment, or build a growth experimentation program....
ad-creative	When the user wants to generate, iterate, or scale ad creative — headlines, descriptions, primary text, or full ad...
ads	When the user wants help with paid advertising campaigns on Google Ads, Meta (Facebook/Instagram), LinkedIn, Twitter/X,...
ai-seo	When the user wants to optimize content for AI search engines, get cited by LLMs, or appear in AI-generated answers....
analytics	When the user wants to set up, improve, or audit analytics tracking and measurement. Also use when the user mentions...
aso	When the user wants to audit or optimize an App Store or Google Play listing. Also use when the user mentions 'ASO...
attribution	When the user wants to figure out which marketing actually drives conversions and revenue, choose or interpret an...
churn-prevention	When the user wants to reduce churn, build cancellation flows, set up save offers, recover failed payments, or...
co-marketing	When the user wants to find co-marketing partners, plan joint campaigns, or brainstorm partnership opportunities. Use...
cold-email	Write B2B cold emails and follow-up sequences that get replies. Use when the user wants to write cold outreach emails,...
community-marketing	Build and leverage online communities to drive product growth and brand loyalty. Use when the user wants to create a...
competitor-profiling	When the user wants to research, profile, or analyze competitors from their URLs. Also use when the user mentions...
competitors	When the user wants to create competitor comparison or alternative pages for SEO and sales enablement. Also use when...
content-strategy	When the user wants to plan a content strategy, decide what content to create, or figure out what topics to cover. Also...
copy-editing	When the user wants to edit, review, or improve existing marketing copy, or refresh outdated content. Also use when the...
copywriting	When the user wants to write, rewrite, or improve marketing copy for any page — including homepage, landing pages,...
cro	When the user wants to optimize, improve, or increase conversions on any marketing page or form — including homepage,...
customer-research	When the user wants to conduct, analyze, or synthesize customer research. Use when the user mentions "customer...
directory-submissions	When the user wants to submit their product to startup, SaaS, AI, agent, MCP, no-code, or review directories for...
emails	When the user wants to create or optimize an email sequence, drip campaign, automated email flow, or lifecycle email...
free-tools	When the user wants to plan, evaluate, or build a free tool for marketing purposes — lead generation, SEO value, or...
image	When the user wants to create, generate, edit, or optimize images for marketing — blog heroes, social graphics, product...
influencer-marketing	When the user wants to run influencer, creator, or ambassador partnerships to promote their product — finding and...
launch	When the user wants to plan a product launch, feature announcement, or release strategy. Also use when the user...
lead-magnets	When the user wants to create, plan, or optimize a lead magnet for email capture or lead generation. Also use when the...
marketing-council	When the user wants multiple expert perspectives on a marketing question — a simulated board of advisors staffed by...
marketing-ideas	When the user needs marketing ideas, inspiration, or strategies for their SaaS or software product. Also use when the...
marketing-loops	When the user wants to set up a recurring, self-running marketing workflow — a repeatable loop an AI agent runs on a...
marketing-plan	When the user needs a comprehensive marketing plan for a client, a company they advise, or their own product. Also use...
marketing-psychology	When the user wants to apply psychological principles, mental models, or behavioral science to marketing. Also use when...
offers	When the user wants to design, construct, or improve an offer — the thing they actually sell — including value framing,...
onboarding	When the user wants to optimize post-signup onboarding, user activation, first-run experience, or time-to-value. Also...
paywalls	When the user wants to create or optimize in-app paywalls, upgrade screens, upsell modals, or feature gates. Also use...
popups	When the user wants to create or optimize popups, modals, overlays, slide-ins, or banners for conversion purposes. Also...
pricing	When the user wants help with pricing decisions, packaging, or monetization strategy. Also use when the user mentions...
product-marketing	When the user wants to create or update their product marketing context document. Also use when the user mentions...
programmatic-seo	When the user wants to create SEO-driven pages at scale using templates and data. Also use when the user mentions...
prospecting	When the user wants to find, qualify, and build a list of prospects to reach out to — across B2B SaaS, general B2B, or...
public-relations	When the user wants help with public relations, earned media, press coverage, journalist outreach, or media strategy...
referrals	When the user wants to create, optimize, or analyze a referral program, affiliate program, or word-of-mouth strategy....
revops	When the user wants help with revenue operations, lead lifecycle management, or marketing-to-sales handoff processes....
sales-enablement	When the user wants to create sales collateral, pitch decks, one-pagers, objection handling docs, or demo scripts. Also...
schema	When the user wants to add, fix, or optimize schema markup and structured data on their site. Also use when the user...
seo-audit	When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO...
signup	When the user wants to optimize signup, registration, account creation, or trial activation flows. Also use when the...
site-architecture	When the user wants to plan, map, or restructure their website's page hierarchy, navigation, URL structure, or internal...
sms	When the user wants to plan, build, or optimize SMS or MMS marketing — including welcome flows, abandoned cart texts,...
social	When the user wants help creating, scheduling, or optimizing social media content for LinkedIn, Twitter/X, Instagram,...
video	When the user wants to create, generate, or produce video content using AI tools or programmatic frameworks. Also use...

Installation

Option 1: CLI Install (Recommended)

Use npx skills to install skills directly:

# Install all skills
npx skills add coreyhaines31/marketingskills

# Install specific skills
npx skills add coreyhaines31/marketingskills --skill cro copywriting

# List available skills
npx skills add coreyhaines31/marketingskills --list

The CLI detects which agents you have installed and asks where to install. For Claude Code it installs into .claude/skills/; universal agents share .agents/skills/.

Tip

If you run the command from inside an agent session (e.g., asking Claude Code to install the skills for you), the CLI runs non-interactively and may only install to the universal .agents/skills/ directory, which Claude Code does not read. Pass the agent explicitly:

npx skills add coreyhaines31/marketingskills -a claude-code

Option 2: Claude Code Plugin

Install via Claude Code's built-in plugin system:

# Add the marketplace
/plugin marketplace add coreyhaines31/marketingskills

# Install all marketing skills
/plugin install marketing-skills

Option 3: Clone and Copy

Clone the entire repo and copy the skills folder:

git clone https://github.com/coreyhaines31/marketingskills.git
cp -r marketingskills/skills/* .agents/skills/

Option 4: Git Submodule

Add as a submodule for easy updates:

git submodule add https://github.com/coreyhaines31/marketingskills.git .agents/marketingskills

Then reference skills from .agents/marketingskills/skills/.

Option 5: Fork and Customize

Fork this repository
Customize skills for your specific needs
Clone your fork into your projects

Option 6: SkillKit (Multi-Agent)

Use SkillKit to install skills across multiple AI agents (Claude Code, Cursor, Copilot, etc.):

# Install all skills
npx skillkit install coreyhaines31/marketingskills

# Install specific skills
npx skillkit install coreyhaines31/marketingskills --skill cro copywriting

# List available skills
npx skillkit install coreyhaines31/marketingskills --list

Upgrading from v1.x to v2.0

v2.0 renames 17 skills and consolidates page-cro + form-cro into a single cro skill. If you installed the v1.x skills, you'll have stale old-name folders in your install directory after upgrading — the new skills install alongside the old ones, so you'll see both skills/page-cro/ and skills/cro/, etc. Clean them up:

# From the directory where you installed the skills (e.g., .agents/skills/ or .claude/skills/)
rm -rf page-cro form-cro \
       ab-test-setup analytics-tracking aso-audit competitor-alternatives \
       email-sequence free-tool-strategy launch-strategy onboarding-cro \
       paid-ads paywall-upgrade-cro popup-cro pricing-strategy \
       product-marketing-context referral-program schema-markup \
       signup-flow-cro social-content

Then reinstall the v2.0 skills via your usual method (e.g., npx skills add coreyhaines31/marketingskills).

Migrate the product marketing context file

In v2.0 the context file moved from .claude/ to .agents/ and was renamed from product-marketing-context.md to product-marketing.md. Move your existing context file:

mkdir -p .agents
# v2.0 file (or pre-v2.0 file with new name)
mv .claude/product-marketing.md .agents/product-marketing.md 2>/dev/null
# pre-v2.0 file with legacy name
mv .claude/product-marketing-context.md .agents/product-marketing.md 2>/dev/null

Skills will still check .claude/ and the legacy product-marketing-context.md filename as fallbacks, so nothing breaks if you don't migrate.

Full rename map

Old	New
`ab-test-setup`	`ab-testing`
`analytics-tracking`	`analytics`
`aso-audit`	`aso`
`competitor-alternatives`	`competitors`
`email-sequence`	`emails`
`form-cro`	merged into `cro`
`free-tool-strategy`	`free-tools`
`launch-strategy`	`launch`
`onboarding-cro`	`onboarding`
`page-cro`	`cro`
`paid-ads`	`ads`
`paywall-upgrade-cro`	`paywalls`
`popup-cro`	`popups`
`pricing-strategy`	`pricing`
`product-marketing-context`	`product-marketing`
`referral-program`	`referrals`
`schema-markup`	`schema`
`signup-flow-cro`	`signup`
`social-content`	`social`

Usage

Once installed, just ask your agent to help with marketing tasks:

"Help me optimize this landing page for conversions"
→ Uses cro skill

"Write homepage copy for my SaaS"
→ Uses copywriting skill

"Set up GA4 tracking for signups"
→ Uses analytics skill

"Create a 5-email welcome sequence"
→ Uses emails skill

You can also invoke skills directly:

/cro
/emails
/seo-audit

Skill Categories

Conversion Optimization

cro - Pages and forms
signup - Registration flows
onboarding - Post-signup activation
popups - Modals and overlays
paywalls - In-app upgrade moments

Content & Copy

copywriting - Marketing page copy
copy-editing - Edit and polish existing copy
cold-email - B2B cold outreach emails and sequences
emails - Automated email flows
social - Social media content
image - AI image generation, design tools, and optimization

SEO & Discovery

seo-audit - Technical and on-page SEO
ai-seo - AI search optimization (AEO, GEO, LLMO)
programmatic-seo - Scaled page generation
site-architecture - Page hierarchy, navigation, URL structure
competitors - Comparison and alternative pages
schema - Structured data

Paid & Distribution

ads - Google, Meta, LinkedIn ad campaigns
ad-creative - Bulk ad creative generation and iteration
social - Social media scheduling and strategy

Measurement & Testing

analytics - Event tracking setup
ab-testing - Experiment design

Retention

churn-prevention - Cancel flows, save offers, dunning, payment recovery

Growth Engineering

co-marketing - Partner identification and joint campaigns
free-tools - Marketing tools and calculators
referrals - Referral and affiliate programs

Strategy & Monetization

marketing-ideas - 140 SaaS marketing ideas
marketing-psychology - Mental models and psychology
launch - Product launches and announcements
pricing - Pricing, packaging, and monetization

Sales & RevOps

revops - Lead lifecycle, scoring, routing, pipeline management
sales-enablement - Sales decks, one-pagers, objection docs, demo scripts

Contributing

Found a way to improve a skill? Have a new skill to suggest? PRs and issues welcome!

See CONTRIBUTING.md for guidelines on adding or improving skills.

License

MIT - Use these however you want.

calesthio/Crucix

Your personal intelligence agent. Watches the world from multiple data sources and pings you when something changes.

Crucix

Your own intelligence terminal. 27 sources. One command. Zero cloud.

Visit The Live Site: crucix.live

Enter The Signal Network

More screenshots

Boot Sequence	World Map

3D Globe View

Live website: https://www.crucix.live/ Explore the public demo first, then clone the repo to run Crucix locally.

Crucix pulls satellite fire detection, flight tracking, radiation monitoring, satellite constellation tracking, economic indicators, live market prices, conflict data, sanctions lists, and social sentiment from 27 open-source intelligence feeds — in parallel, every 15 minutes — and renders everything on a single self-contained Jarvis-style dashboard.

Hook it up to an LLM and it becomes a two-way intelligence assistant — pushing multi-tier alerts to Telegram and Discord when something meaningful changes, responding to commands like /brief and /sweep from your phone, and generating actionable trade ideas grounded in real cross-domain data. Your own analyst that watches the world while you sleep.

Try the live demo first at https://www.crucix.live/, then clone the repo when you want the full local stack.

No cloud. No telemetry. No subscriptions. Just node server.mjs and you're running.

Token / Asset Warning

Warning

Crucix has not launched any official token, coin, NFT, airdrop, presale, or other blockchain-based asset. Any token or digital asset using the Crucix name, logo, or branding is not affiliated with or endorsed by Crucix. Do not buy it, promote it, connect a wallet to claim it, sign transactions, or send funds based on third-party posts, DMs, or websites.

Why This Exists

Most of the world's real-time intelligence — satellite imagery, radiation levels, conflict events, economic indicators, flight tracking, maritime activity — is publicly available. It's just scattered across dozens of government APIs, research institutions, and open data feeds that nobody has time to check individually.

Crucix brings it all into one place. Not behind a paywall, not locked in an enterprise platform, not requiring a security clearance. Just open data, aggregated and cross-correlated on your own machine, updated every 15 minutes.

It was built for anyone who wants to understand what's actually happening in the world right now — researchers, journalists, traders, OSINT analysts, or just curious people who believe access to information shouldn't depend on your budget.

Quick Start

# 1. Clone the repo
git clone https://github.com/calesthio/Crucix.git
cd Crucix

# 2. Install dependencies (just Express)
npm install

# 3. Copy env template and add your API keys (see below)
cp .env.example .env

# 4. Start the dashboard
npm run dev

If npm run dev fails silently (exits with no output), run Node directly instead:
node --trace-warnings server.mjs
This bypasses npm's script runner, which can swallow errors on some systems (particularly PowerShell on Windows). You can also run node diag.mjs to diagnose the exact issue — it checks your Node version, tests each module import individually, and verifies port availability. See Troubleshooting for more.

The dashboard opens automatically at http://localhost:3117 and immediately begins its first intelligence sweep. This initial sweep queries all 27 sources in parallel and typically takes 30–60 seconds — the dashboard will appear empty until the sweep completes and pushes the first data update. After that, it auto-refreshes every 15 minutes via SSE (Server-Sent Events). No manual page refresh needed.

Requirements: Node.js 22+ (uses native fetch, top-level await, ESM)

Docker

git clone https://github.com/calesthio/Crucix.git
cd Crucix
cp .env.example .env    # add your API keys
docker compose up -d

Dashboard at http://localhost:3117. Sweep data persists in ./runs/ via volume mount. Includes a health check endpoint.

What You Get

Live Dashboard

A self-contained Jarvis-style HUD with:

3D WebGL globe (Globe.gl) with atmosphere glow, star field, and smooth rotation — plus a classic flat map toggle
9 marker types across both views: fire detections, air traffic, radiation sites, maritime chokepoints, SDR receivers, OSINT events, health alerts, geolocated news, conflict events
Animated 3D flight corridor arcs between air traffic hotspots and global hubs
Region filters (World, Americas, Europe, Middle East, Asia Pacific, Africa) — rotates the globe or zooms the flat map
Live market data — indexes, crypto, energy, commodities via Yahoo Finance (no API key needed)
Risk gauges — VIX, high-yield spread, supply chain pressure index
OSINT feed — English-language posts from 17 Telegram intelligence channels (expandable)
News ticker — merged RSS + GDELT headlines + Telegram posts, auto-scrolling
Sweep delta — live panel showing what changed since last sweep (new signals, escalations, de-escalations with severity)
Cross-source signals — correlated intelligence across satellite, economic, conflict, and social domains
Nuclear watch — real-time radiation readings from Safecast + EPA RadNet
Space watch — CelesTrak satellite tracking: recent launches, ISS, military constellations, Starlink/OneWeb counts
Leverageable ideas — AI-generated trade ideas (with LLM) or signal-correlated ideas (without)

Performance Modes

The VISUALS FULL / VISUALS LITE button in the top bar only changes rendering behavior - it does not remove data sources or reduce sweep coverage.

When you switch to VISUALS LITE, the dashboard:

Disables decorative background effects such as the radial/grid overlays and scanlines
Removes expensive blur/backdrop-filter effects on panels and overlays
Stops non-essential animations like the logo ring blink, conflict rings, and corridor flow effects
Disables globe auto-rotation and turns off animated flight-arc dashes
Converts the horizontal news ticker and OSINT stream into static, scrollable lists instead of continuously animated marquees

Mobile-specific behavior:

On mobile, VISUALS LITE also forces the dashboard into flat map mode if you are currently on the globe
Future mobile loads will continue to start flat while low-perf mode is enabled

The preference is saved in browser local storage, so the UI will remember your last setting.

Auto-Refresh

The server runs a sweep cycle every 15 minutes (configurable). Each cycle:

Queries all 27 sources in parallel (~30s)
Synthesizes raw data into dashboard format
Computes delta from previous run (what changed, escalated, de-escalated) — visible in the Sweep Delta panel on the dashboard
Generates LLM trade ideas (if configured)
Evaluates breaking news alerts — multi-tier (FLASH / PRIORITY / ROUTINE) with semantic dedup. Sends to Telegram and/or Discord if configured. Works with LLM evaluation or falls back to rule-based alerting when LLM is unavailable.
Pushes update to all connected browsers via SSE

Telegram Bot (Two-Way)

Crucix doubles as an interactive Telegram bot. Beyond sending alerts, it responds to commands directly from your chat:

Command	What It Does
`/status`	System health, last sweep time, source status, LLM status
`/sweep`	Trigger a manual sweep cycle
`/brief`	Compact text summary of the latest intelligence (direction, key metrics, top OSINT)
`/portfolio`	Portfolio status (if Alpaca connected)
`/alerts`	Recent alert history with tiers
`/mute` / `/mute 2h`	Silence alerts for 1h (or custom duration)
`/unmute`	Resume alerts
`/help`	Show all available commands

This requires TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID in .env. The bot polls for messages every 5 seconds (configurable via TELEGRAM_POLL_INTERVAL).

Discord Bot (Two-Way)

Crucix also supports Discord as a full-featured bot with slash commands and rich embed alerts. It mirrors the Telegram bot's capabilities with Discord-native formatting.

Command	What It Does
`/status`	System health, last sweep time, source status, LLM status
`/sweep`	Trigger a manual sweep cycle
`/brief`	Compact text summary of the latest intelligence
`/portfolio`	Portfolio status (if Alpaca connected)

Alerts are delivered as rich embeds with color-coded sidebars: red for FLASH, yellow for PRIORITY, blue for ROUTINE. Each embed includes signal details, confidence scores, and cross-domain correlations.

Setup requires: DISCORD_BOT_TOKEN, DISCORD_CHANNEL_ID, and optionally DISCORD_GUILD_ID for instant slash command registration. See API Keys Setup for details.

Webhook fallback: If you don't want to run a full bot, set DISCORD_WEBHOOK_URL instead. This enables one-way alerts (no slash commands) with zero dependencies — no discord.js needed.

Optional dependency: The full bot requires discord.js. Install it with npm install discord.js. If it's not installed, Crucix automatically falls back to webhook-only mode.

Optional LLM Layer

Connect any of 8 LLM providers for enhanced analysis:

AI trade ideas — quantitative analyst producing 5-8 actionable ideas citing specific data
Smarter alert evaluation — LLM classifies signals into FLASH/PRIORITY/ROUTINE tiers with cross-domain correlation and confidence scoring
Providers: Anthropic Claude, OpenAI, Google Gemini, OpenRouter (Unified API), OpenAI Codex (ChatGPT subscription), MiniMax, Mistral, Grok
Graceful fallback — when LLM is unavailable, a rule-based engine takes over alert evaluation. LLM failures never crash the sweep cycle.

API Keys Setup

Copy .env.example to .env at the project root:

cp .env.example .env

Required for Best Results (all free)

Key	Source	How to Get
`FRED_API_KEY`	Federal Reserve Economic Data	fred.stlouisfed.org — instant, free
`FIRMS_MAP_KEY`	NASA FIRMS (satellite fire data)	firms.modaps.eosdis.nasa.gov — instant, free
`EIA_API_KEY`	US Energy Information Administration	api.eia.gov — instant, free

These three unlock the most valuable economic and satellite data. Each takes about 60 seconds to register.

Optional (enable additional sources)

Key	Source	How to Get
`ACLED_EMAIL` + `ACLED_PASSWORD`	Armed conflict event data	acleddata.com/register — free, OAuth2
`AISSTREAM_API_KEY`	Maritime AIS vessel tracking	aisstream.io — free
`ADSB_API_KEY`	Unfiltered flight tracking	RapidAPI — ~$10/mo

LLM Provider (optional, for AI-enhanced ideas)

Set LLM_PROVIDER to one of: anthropic, openai, gemini, codex, openrouter, minimax, mistral, grok

Provider	Key Required	Default Model
`anthropic`	`LLM_API_KEY`	claude-sonnet-4-6
`openai`	`LLM_API_KEY`	gpt-5.4
`gemini`	`LLM_API_KEY`	gemini-3.1-pro
`openrouter`	`LLM_API_KEY`	openrouter/auto
`codex`	None (uses `~/.codex/auth.json`)	gpt-5.3-codex
`minimax`	`LLM_API_KEY`	MiniMax-M2.5
`mistral`	`LLM_API_KEY`	mistral-large-latest
`grok`	`LLM_API_KEY`	grok-4-latest

For Codex, run npx @openai/codex login to authenticate via your ChatGPT subscription.

Telegram Bot + Alerts (optional)

Key	How to Get
`TELEGRAM_BOT_TOKEN`	Create via @BotFather on Telegram
`TELEGRAM_CHAT_ID`	Get via @userinfobot
`TELEGRAM_CHANNELS`	(Optional) Comma-separated extra channel IDs to monitor beyond the 17 built-in channels
`TELEGRAM_POLL_INTERVAL`	(Optional) Bot command polling interval in ms (default: 5000)

Discord Bot + Alerts (optional)

Key	How to Get
`DISCORD_BOT_TOKEN`	Create at Discord Developer Portal → Bot → Token
`DISCORD_CHANNEL_ID`	Right-click channel in Discord (Developer Mode on) → Copy Channel ID
`DISCORD_GUILD_ID`	(Optional) Right-click server → Copy Server ID. Enables instant slash command registration (otherwise takes up to 1 hour for global commands)
`DISCORD_WEBHOOK_URL`	(Optional) Channel Settings → Integrations → Webhooks → New Webhook → Copy URL. Use this for alert-only mode without a bot

Discord bot setup:

Go to Discord Developer Portal and create a new application
Go to Bot → click Reset Token → copy the token to DISCORD_BOT_TOKEN
Under Privileged Gateway Intents, enable Message Content Intent
Go to OAuth2 → URL Generator → select bot + applications.commands scopes → select Send Messages + Embed Links permissions
Copy the generated URL and open it in your browser to invite the bot to your server
Install the dependency: npm install discord.js

Alerts work with or without an LLM on both Telegram and Discord. With an LLM configured, signal evaluation is richer and more context-aware. Without one, a deterministic rule engine evaluates signals based on severity, cross-domain correlation, and signal counts.

Without Any Keys

Crucix still works with zero API keys. 18+ sources require no authentication at all. Sources that need keys return structured errors and the rest of the sweep continues normally.

Architecture

crucix/
├── server.mjs                 # Express dev server (SSE, auto-refresh, LLM, bot commands)
├── crucix.config.mjs          # Configuration with env var overrides + delta thresholds
├── diag.mjs                   # Diagnostic script — run if server fails to start
├── .env.example               # All documented env vars
├── package.json               # Runtime: express | Optional: discord.js
├── docs/                      # Screenshots for README
│
├── apis/
│   ├── briefing.mjs           # Master orchestrator — runs all 27 sources in parallel
│   ├── save-briefing.mjs      # CLI: save timestamped + latest.json
│   ├── BRIEFING_PROMPT.md     # Intelligence synthesis protocol
│   ├── BRIEFING_TEMPLATE.md   # Briefing output structure
│   ├── utils/
│   │   ├── fetch.mjs          # safeFetch() — timeout, retries, abort, auto-JSON
│   │   └── env.mjs            # .env loader (no dotenv dependency)
│   └── sources/               # 27 self-contained source modules
│       ├── gdelt.mjs          # Each exports briefing() → structured data
│       ├── fred.mjs           # Can run standalone: node apis/sources/fred.mjs
│       ├── space.mjs          # CelesTrak satellite tracking
│       ├── yfinance.mjs       # Yahoo Finance — free live market data
│       └── ...                # 23 more
│
├── dashboard/
│   ├── inject.mjs             # Data synthesis + standalone HTML injection
│   └── public/
│       └── jarvis.html        # Self-contained Jarvis HUD
│
├── lib/
│   ├── llm/                   # LLM abstraction (8 providers, raw fetch, no SDKs)
│   │   ├── provider.mjs       # Base class
│   │   ├── anthropic.mjs      # Claude
│   │   ├── openai.mjs         # GPT
│   │   ├── gemini.mjs         # Gemini
│   │   ├── grok.mjs           # Grok
│   │   ├── openrouter.mjs     # OpenRouter (Unified API)
│   │   ├── codex.mjs          # Codex (ChatGPT subscription)
│   │   ├── minimax.mjs        # MiniMax (M2.5, 204K context)
│   │   ├── mistral.mjs        # Mistral AI
│   │   ├── ideas.mjs          # LLM-powered trade idea generation
│   │   └── index.mjs          # Factory: createLLMProvider()
│   ├── delta/                 # Change tracking between sweeps
│   │   ├── engine.mjs         # Delta computation — semantic dedup, configurable thresholds, severity scoring
│   │   ├── memory.mjs         # Hot memory (3 runs, atomic writes) + cold storage (daily archives)
│   │   └── index.mjs          # Re-exports
│   └── alerts/
│       ├── telegram.mjs       # Multi-tier alerts (FLASH/PRIORITY/ROUTINE) + two-way bot commands
│       └── discord.mjs        # Discord bot (slash commands, rich embeds) + webhook fallback
│
└── runs/                      # Runtime data (gitignored)
    ├── latest.json            # Most recent sweep output
    └── memory/                # Delta memory (hot.json + cold/YYYY-MM-DD.json)

Design Principles

Pure ESM — every file is .mjs with explicit imports
Minimal dependencies — Express is the only runtime dependency. discord.js is optional (for Discord bot). LLM providers use raw fetch(), no SDKs.
Parallel execution — Promise.allSettled() fires all 27 sources simultaneously
Graceful degradation — missing keys produce errors, not crashes. LLM failures don't kill sweeps.
Each source is standalone — run node apis/sources/gdelt.mjs to test any source independently
Self-contained dashboard — the HTML file works with or without the server

Data Sources (27)

Tier 1: Core OSINT & Geopolitical (11)

Source	What It Tracks	Auth
GDELT	Global news events, conflict mapping (100+ languages)	None
OpenSky	Real-time ADS-B flight tracking across 6 hotspot regions	None
NASA FIRMS	Satellite fire/thermal anomaly detection (3hr latency)	Free key
Maritime/AIS	Vessel tracking, dark ships, sanctions evasion	Free key
Safecast	Citizen-science radiation monitoring near 6 nuclear sites	None
ACLED	Armed conflict events: battles, explosions, protests	Free (OAuth2)
ReliefWeb	UN humanitarian crisis tracking	None
WHO	Disease outbreaks and health emergencies	None
OFAC	US Treasury sanctions (SDN list)	None
OpenSanctions	Aggregated global sanctions (30+ sources)	Partial
ADS-B Exchange	Unfiltered flight tracking including military	Paid

Tier 2: Economic & Financial (7)

Source	What It Tracks	Auth
FRED	22 key indicators: yield curve, CPI, VIX, fed funds, M2	Free key
US Treasury	National debt, yields, fiscal data	None
BLS	CPI, unemployment, nonfarm payrolls, PPI	None
EIA	WTI/Brent crude, natural gas, inventories	Free key
GSCPI	NY Fed Global Supply Chain Pressure Index	None
USAspending	Federal spending and defense contracts	None
UN Comtrade	Strategic commodity trade flows between major powers	None

Tier 3: Weather, Environment, Tech, Social, SIGINT (7)

Source	What It Tracks	Auth
NOAA/NWS	Active US weather alerts	None
EPA RadNet	US government radiation monitoring	None
USPTO Patents	Patent filings in 7 strategic tech areas	None
Bluesky	Social sentiment on geopolitical/market topics	None
Reddit	Social sentiment from key subreddits	OAuth
Telegram	17 curated OSINT/conflict/finance channels (web scraping, expandable via config)	None
KiwiSDR	Global HF radio receiver network (~600 receivers)	None

Tier 4: Space & Satellites (1)

Source	What It Tracks	Auth
CelesTrak	Satellite launches, ISS tracking, military constellations, Starlink/OneWeb counts	None

Tier 5: Live Market Data (1)

Source	What It Tracks	Auth
Yahoo Finance	Real-time prices: SPY, QQQ, BTC, Gold, WTI, VIX + 9 more	None

npm Scripts

Script	Command	Description
`npm run dev`	`node --trace-warnings server.mjs`	Start dashboard with auto-refresh
`npm run sweep`	`node apis/briefing.mjs`	Run a single sweep, output JSON to stdout
`npm run inject`	`node dashboard/inject.mjs`	Inject latest data into static HTML
`npm run brief:save`	`node apis/save-briefing.mjs`	Run sweep + save timestamped JSON
`npm run diag`	`node diag.mjs`	Run diagnostics (Node version, imports, port check)

Configuration

All settings are in .env with sensible defaults:

Variable	Default	Description
`PORT`	`3117`	Dashboard server port
`REFRESH_INTERVAL_MINUTES`	`15`	Auto-refresh interval
`LLM_PROVIDER`	disabled	`anthropic`, `openai`, `gemini`, `codex`, `openrouter`, `minimax`, `mistral`, or `grok`
`LLM_API_KEY`	—	API key (not needed for codex)
`LLM_MODEL`	per-provider default	Override model selection
`TELEGRAM_BOT_TOKEN`	disabled	For Telegram alerts + bot commands
`TELEGRAM_CHAT_ID`	—	Your Telegram chat ID
`TELEGRAM_CHANNELS`	—	Extra channel IDs to monitor (comma-separated)
`TELEGRAM_POLL_INTERVAL`	`5000`	Bot command polling interval (ms)
`DISCORD_BOT_TOKEN`	disabled	For Discord alerts + slash commands
`DISCORD_CHANNEL_ID`	—	Discord channel for alerts
`DISCORD_GUILD_ID`	—	Server ID (instant slash command registration)
`DISCORD_WEBHOOK_URL`	—	Webhook URL (alert-only fallback, no bot needed)

Delta engine thresholds (how sensitive the system is to changes between sweeps) can be customized in crucix.config.mjs under the delta.thresholds section. The defaults are tuned to filter out noise while catching meaningful moves.

API Endpoints

When running npm run dev:

Endpoint	Description
`GET /`	Jarvis HUD dashboard
`GET /api/data`	Current synthesized intelligence data (JSON)
`GET /api/health`	Server status, uptime, source count, LLM status
`GET /events`	SSE stream for live push updates

Troubleshooting

`npm run dev` exits silently (no output, no error)

This is a known issue where npm's script runner can swallow errors, particularly on Windows PowerShell. Try these in order:

1. Run Node directly (bypasses npm):

node --trace-warnings server.mjs

This is functionally identical to npm run dev but gives you full error output.

2. Run the diagnostic script:

node diag.mjs

This tests every import one by one, checks your Node.js version, and verifies port 3117 is available. It will tell you exactly what's failing.

3. Check if port 3117 is already in use:

A previous Crucix instance may still be running in the background.

# Windows PowerShell
netstat -ano | findstr 3117
taskkill /F /PID <the_PID_from_above>

# Or kill all Node processes
taskkill /F /IM node.exe

# macOS / Linux
lsof -ti:3117 | xargs kill

Then try starting again. You can also change the port by setting PORT=3118 in your .env file.

4. Check Node.js version:

node --version

Crucix requires Node.js 22 or later. If you have an older version, download the latest LTS from nodejs.org.

Dashboard shows empty panels after first start

This is normal — the first sweep takes 30–60 seconds to query all 27 sources. The dashboard will populate automatically once the sweep completes. Check the terminal for sweep progress logs.

Some sources show errors

Expected behavior. Sources that require API keys will return structured errors if the key isn't set. The rest of the sweep continues normally. Check the Source Integrity section in the dashboard (or the server logs) to see which sources failed and why. The 3 most impactful free keys to add are FRED_API_KEY, FIRMS_MAP_KEY, and EIA_API_KEY.

OpenSky can also return HTTP 429 when its public hotspots are queried too aggressively. Crucix does not try to evade that limit. Instead, it surfaces the throttle/error in source health and preserves the most recent non-empty air traffic snapshot from runs/ so the dashboard flight layer does not suddenly go blank on a throttled sweep.

Telegram bot not responding to commands

Make sure both TELEGRAM_BOT_TOKEN and TELEGRAM_CHAT_ID are set in .env. The bot only responds to messages from the configured chat ID (security measure). You should see [Crucix] Telegram alerts enabled and [Crucix] Bot command polling started in the server logs on startup. If not, double-check your token with curl https://api.telegram.org/bot<YOUR_TOKEN>/getMe.

Discord bot not responding to slash commands

Check these in order:

Make sure DISCORD_BOT_TOKEN and DISCORD_CHANNEL_ID are set in .env
Verify discord.js is installed: npm ls discord.js. If missing, run npm install discord.js
If slash commands don't appear, set DISCORD_GUILD_ID — without it, global commands can take up to 1 hour to propagate. Guild-specific commands register instantly
Confirm the bot was invited with bot + applications.commands scopes and has Send Messages + Embed Links permissions in the target channel
Check server logs for [Discord] Bot logged in as ... on startup. If you see [Discord] discord.js not installed, install it and restart
Webhook-only fallback: If you just want alerts without slash commands, set DISCORD_WEBHOOK_URL instead of the bot token. No discord.js needed.

Screenshots

The docs/ folder contains dashboard screenshots referenced by this README:

File	Description
`docs/dashboard.png`	Full dashboard — hero image at the top of this README
`docs/boot.png`	Cinematic boot sequence animation
`docs/map.png`	D3 world map with marker types and flight arcs
`docs/globe.png`	3D WebGL globe view with atmosphere glow and markers

To update them: run the dashboard, wait for a sweep to complete, then use your browser's DevTools (F12 → Ctrl+Shift+P → "Capture full size screenshot") or a tool like LICEcap for GIFs.

Contributing

Found a bug? Want to add a 28th source? PRs welcome. Each source is a standalone module in apis/sources/ — just export a briefing() function that returns structured data and add it to the orchestrator in apis/briefing.mjs.

If you find this useful, a star helps others find it too.

For contribution guidelines, review expectations, and source-add rules, see CONTRIBUTING.md. For security reports, see SECURITY.md.

Contact

For partnerships, integrations, or other non-issue inquiries, you can reach me at celesthioailabs@gmail.com.

For bugs and feature requests, please use GitHub Issues so discussion stays visible and actionable.

Star History

License

AGPL-3.0

eyaltoledano/claude-task-master

An AI-powered task-management system you can drop into Cursor, Lovable, Windsurf, Roo, and others.

Taskmaster: A task management system for AI-driven development, designed to work seamlessly with any AI chat.

| Docs

By @eyaltoledano & @RalphEcom

A task management system for AI-driven development with Claude, designed to work seamlessly with Cursor AI.

Documentation

📚 View Full Documentation

Quick Links

More from Hamster

Quick Install for Cursor 1.0+ (One-Click)

Note: After clicking the link, you'll still need to add your API keys to the configuration. The link installs the MCP server with placeholder keys that you'll need to replace with your actual API keys.

Claude Code Quick Install

For Claude Code users:

claude mcp add taskmaster-ai -- npx -y task-master-ai

Don't forget to add your API keys to the configuration:

in the root .env of your Project
in the "env" section of your mcp config for taskmaster-ai

Requirements

Taskmaster utilizes AI across several commands, and those require a separate API key. You can use a variety of models from different AI providers provided you add your API keys. For example, if you want to use Claude 3.7, you'll need an Anthropic API key.

You can define 3 types of models to be used: the main model, the research model, and the fallback model (in case either the main or research fail). Whatever model you use, its provider API key must be present in either mcp.json or .env.

At least one (1) of the following is required:

Anthropic API key (Claude API)
OpenAI API key
Google Gemini API key
Perplexity API key (for research model)
xAI API Key (for research or main model)
OpenRouter API Key (for research or main model)
Claude Code (no API key required - requires Claude Code CLI)
Codex CLI (OAuth via ChatGPT subscription - requires Codex CLI)

Using the research model is optional but highly recommended. You will need at least ONE API key (unless using Claude Code or Codex CLI with OAuth). Adding all API keys enables you to seamlessly switch between model providers at will.

Quick Start

Option 1: MCP (Recommended)

MCP (Model Control Protocol) lets you run Task Master directly from your editor.

1. Add your MCP config at the following path depending on your editor

Editor	Scope	Linux/macOS Path	Windows Path	Key
Cursor	Global	`~/.cursor/mcp.json`	`%USERPROFILE%\.cursor\mcp.json`	`mcpServers`
	Project	`<project_folder>/.cursor/mcp.json`	`<project_folder>\.cursor\mcp.json`	`mcpServers`
Windsurf	Global	`~/.codeium/windsurf/mcp_config.json`	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`	`mcpServers`
VS Code	Project	`<project_folder>/.vscode/mcp.json`	`<project_folder>\.vscode\mcp.json`	`servers`
Q CLI	Global	`~/.aws/amazonq/mcp.json`		`mcpServers`

Manual Configuration

Cursor & Windsurf & Q Developer CLI (`mcpServers`)

{
  "mcpServers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        // "TASK_MASTER_TOOLS": "all", // Options: "all", "standard", "core", or comma-separated list of tools
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
        "GROQ_API_KEY": "YOUR_GROQ_KEY_HERE",
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE"
      }
    }
  }
}

🔑 Replace YOUR_…_KEY_HERE with your real API keys. You can remove keys you don't use.

Note: If you see 0 tools enabled in the MCP settings, restart your editor and check that your API keys are correctly configured.

VS Code (`servers` + `type`)

{
  "servers": {
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        // "TASK_MASTER_TOOLS": "all", // Options: "all", "standard", "core", or comma-separated list of tools
        "ANTHROPIC_API_KEY": "YOUR_ANTHROPIC_API_KEY_HERE",
        "PERPLEXITY_API_KEY": "YOUR_PERPLEXITY_API_KEY_HERE",
        "OPENAI_API_KEY": "YOUR_OPENAI_KEY_HERE",
        "GOOGLE_API_KEY": "YOUR_GOOGLE_KEY_HERE",
        "MISTRAL_API_KEY": "YOUR_MISTRAL_KEY_HERE",
        "GROQ_API_KEY": "YOUR_GROQ_KEY_HERE",
        "OPENROUTER_API_KEY": "YOUR_OPENROUTER_KEY_HERE",
        "XAI_API_KEY": "YOUR_XAI_KEY_HERE",
        "AZURE_OPENAI_API_KEY": "YOUR_AZURE_KEY_HERE",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY_HERE"
      },
      "type": "stdio"
    }
  }
}

🔑 Replace YOUR_…_KEY_HERE with your real API keys. You can remove keys you don't use.

2. (Cursor-only) Enable Taskmaster MCP

Open Cursor Settings (Ctrl+Shift+J) ➡ Click on MCP tab on the left ➡ Enable task-master-ai with the toggle

3. (Optional) Configure the models you want to use

In your editor's AI chat pane, say:

Change the main, research and fallback models to <model_name>, <model_name> and <model_name> respectively.

For example, to use Claude Code (no API key required):

Change the main model to claude-code/sonnet

Table of available models | Claude Code setup

4. Initialize Task Master

In your editor's AI chat pane, say:

Initialize taskmaster-ai in my project

5. Make sure you have a PRD (Recommended)

For new projects: Create your PRD at .taskmaster/docs/prd.txt. For existing projects: You can use scripts/prd.txt or migrate with task-master migrate

An example PRD template is available after initialization in .taskmaster/templates/example_prd.txt.

Note

While a PRD is recommended for complex projects, you can always create individual tasks by asking "Can you help me implement [description of what you want to do]?" in chat.

Always start with a detailed PRD.

The more detailed your PRD, the better the generated tasks will be.

6. Common Commands

Use your AI assistant to:

Parse requirements: Can you parse my PRD at scripts/prd.txt?
Plan next step: What's the next task I should work on?
Implement a task: Can you help me implement task 3?
View multiple tasks: Can you show me tasks 1, 3, and 5?
Expand a task: Can you help me expand task 4?
Research fresh information: Research the latest best practices for implementing JWT authentication with Node.js
Research with context: Research React Query v5 migration strategies for our current API implementation in src/api.js

More examples on how to use Task Master in chat

Option 2: Using Command Line

Installation

# Install globally
npm install -g task-master-ai

# OR install locally within your project
npm install task-master-ai

Initialize a new project

# If installed globally
task-master init

# If installed locally
npx task-master init

# Initialize project with specific rules
task-master init --rules cursor,windsurf,vscode

This will prompt you for project details and set up a new project with the necessary files and structure.

Common Commands

# Initialize a new project
task-master init

# Parse a PRD and generate tasks
task-master parse-prd your-prd.txt

# List all tasks
task-master list

# Show the next task to work on
task-master next

# Show specific task(s) - supports comma-separated IDs
task-master show 1,3,5

# Research fresh information with project context
task-master research "What are the latest best practices for JWT authentication?"

# Move tasks between tags (cross-tag movement)
task-master move --from=5 --from-tag=backlog --to-tag=in-progress
task-master move --from=5,6,7 --from-tag=backlog --to-tag=done --with-dependencies
task-master move --from=5 --from-tag=backlog --to-tag=in-progress --ignore-dependencies

# Add rules after initialization
task-master rules add windsurf,roo,vscode

Tool Loading Configuration

Optimizing MCP Tool Loading

Task Master's MCP server supports selective tool loading to reduce context window usage. By default, all 36 tools are loaded (~21,000 tokens) to maintain backward compatibility with existing installations.

You can optimize performance by configuring the TASK_MASTER_TOOLS environment variable:

Available Modes

Mode	Tools	Context Usage	Use Case
`all` (default)	36	~21,000 tokens	Complete feature set - all tools available
`standard`	15	~10,000 tokens	Common task management operations
`core` (or `lean`)	7	~5,000 tokens	Essential daily development workflow
`custom`	Variable	Variable	Comma-separated list of specific tools

Configuration Methods

Method 1: Environment Variable in MCP Configuration

Add TASK_MASTER_TOOLS to your MCP configuration file's env section:

{
  "mcpServers": {  // or "servers" for VS Code
    "task-master-ai": {
      "command": "npx",
      "args": ["-y", "task-master-ai"],
      "env": {
        "TASK_MASTER_TOOLS": "standard",  // Options: "all", "standard", "core", "lean", or comma-separated list
        "ANTHROPIC_API_KEY": "your-key-here",
        // ... other API keys
      }
    }
  }
}

Method 2: Claude Code CLI (One-Time Setup)

For Claude Code users, you can set the mode during installation:

# Core mode example (~70% token reduction)
claude mcp add task-master-ai --scope user \
  --env TASK_MASTER_TOOLS="core" \
  -- npx -y task-master-ai@latest

# Custom tools example
claude mcp add task-master-ai --scope user \
  --env TASK_MASTER_TOOLS="get_tasks,next_task,set_task_status" \
  -- npx -y task-master-ai@latest

Tool Sets Details

Core Tools (7): get_tasks, next_task, get_task, set_task_status, update_subtask, parse_prd, expand_task

Standard Tools (15): All core tools plus initialize_project, analyze_project_complexity, expand_all, add_subtask, remove_task, generate, add_task, complexity_report

All Tools (36): Complete set including project setup, task management, analysis, dependencies, tags, research, and more

Recommendations

New users: Start with "standard" mode for a good balance
Large projects: Use "core" mode to minimize token usage
Complex workflows: Use "all" mode or custom selection
Backward compatibility: If not specified, defaults to "all" mode

Claude Code Support

Task Master now supports Claude models through the Claude Code CLI, which requires no API key:

Models: claude-code/opus and claude-code/sonnet
Requirements: Claude Code CLI installed
Benefits: No API key needed, uses your local Claude instance

Learn more about Claude Code setup

Troubleshooting

If `task-master init` doesn't respond

Try running it with Node directly:

node node_modules/claude-task-master/scripts/init.js

Or clone the repository and run:

git clone https://github.com/eyaltoledano/claude-task-master.git
cd claude-task-master
node scripts/init.js

Join Our Team

Contributors

Star History

Licensing

Task Master is licensed under the MIT License with Commons Clause. This means you can:

✅ Allowed:

Use Task Master for any purpose (personal, commercial, academic)
Modify the code
Distribute copies
Create and sell products built using Task Master

❌ Not Allowed:

Sell Task Master itself
Offer Task Master as a hosted service
Create competing products based on Task Master

See the LICENSE file for the complete license text and licensing details for more information.

DietrichGebert/ponytail

Makes your AI agent think like the laziest senior dev in the room. The best code is the code you never wrote.

Ponytail

He says nothing. He writes one line. It works.

~54% less code (up to 94%) · ~20% cheaper · ~27% faster · 100% safe
_{Measured on real Claude Code sessions editing a real open-source repo (FastAPI + React), against the same agent with no skill. ~54% is the mean across 12 feature tasks (Haiku 4.5, n=4); it reaches 94% where an agent over-builds (a date picker) and is near zero where the code is already minimal. ponytail keeps every safety guard while a bare "write one-liners" prompt drops one. (The earlier single-shot benchmark reported 80-94% as a flat figure; against a fair agentic baseline that is the per-task ceiling, not the average.) Full writeup · reproduce it.}

_{Español · 한국어}

You know him. Long ponytail. Oval glasses. Has been at the company longer than the version control. You show him fifty lines; he looks at them, says nothing, and replaces them with one.

Ponytail puts him inside your AI agent.

Before / after

You ask for a date picker. Your agent installs flatpickr, writes a wrapper component, adds a stylesheet, and starts a discussion about timezones.

With ponytail:

<!-- ponytail: browser has one -->
<input type="date">

More survivors in examples/.

Numbers

The honest measurement is a real agent doing real work: a headless Claude Code session editing tiangolo's full-stack-fastapi-template (a real FastAPI + React repo), scored on the git diff it leaves behind. Twelve feature tickets, the same agent with and without the skill, n=4, Haiku 4.5.

vs no-skill baseline	LOC	tokens	cost	time	safe
ponytail	-54%	-22%	-20%	-27%	100%
caveman (terse-prose control)	-20%	+7%	+3%	+2%	100%
"YAGNI + one-liners" prompt	-33%	-14%	-21%	-30%	95%

ponytail is the only arm that cuts every metric, and the only one that stays fully safe while doing it. The cut is biggest where there is a real over-build trap (date picker 404 to 23 lines, color picker 287 to 23, because it reaches for a native <input> instead of a component) and near zero on code that is already minimal. Full method, per-task tables, and limitations: benchmarks/results/2026-06-18-agentic.md.

Older single-shot numbers (isolated generation)

Five everyday tasks, three models, three arms (no skill, caveman, ponytail), ten runs, median reported. One prompt, one completion, counting lines of the answer:

This showed 80-94% less code. #126 fairly pointed out that the bare-model baseline pads its answer with prose and options, so that gap is partly a conversational-baseline artifact. The agentic numbers above are the corrected, defensible version. Reproduce the single-shot run with npx promptfoo eval -c benchmarks/promptfooconfig.yaml.

The rule was never "fewest tokens." It is: write only what the task needs, and never cut validation, error handling, security, or accessibility. The code ends up small because it is necessary, not golfed. Lower cost and latency are a side effect on the models that follow the ladder; a terse reasoning model that spends thinking tokens deliberating the rungs can go the other way (on GPT-5.5 it does).

How it works

Before writing code, the agent stops at the first rung that holds:

1. Does this need to exist?   → no: skip it (YAGNI)
2. Already in this codebase?  → reuse it, don't rewrite
3. Stdlib does it?            → use it
4. Native platform feature?   → use it
5. Installed dependency?      → use it
6. One line?                  → one line
7. Only then: the minimum that works

The ladder runs after it understands the problem, not instead of it: it reads the code the change touches and traces the real flow before picking a rung. Lazy about the solution, never about reading.

Lazy, not negligent: trust-boundary validation, data-loss handling, security, and accessibility are never on the chopping block.

Install

The most effort ponytail will ever ask of you:

The Claude Code and Codex plugins run two tiny Node.js lifecycle hooks, so node needs to be on your PATH (note for Nix/nvm users: it must be on the non-interactive shell's PATH). If it isn't, the skills still work, the always-on activation just stays quiet instead of erroring on every prompt.

Claude Code

/plugin marketplace add DietrichGebert/ponytail

/plugin install ponytail@ponytail

(You have to send two separate prompts for the install to work)

Same steps in the Claude Code Desktop app's Code tab: type the two /plugin commands above into the prompt box, or click the + button next to it, choose Plugins → Add plugin to browse your configured marketplaces, and manage marketplaces from Customize in the sidebar.

Codex

codex plugin marketplace add DietrichGebert/ponytail
codex plugin add ponytail@ponytail

Run codex and open /hooks, review and trust its two lifecycle hooks, and start a new thread.

This same install also covers the Codex desktop app: restart the app after installing and it picks up the plugin.

GitHub Copilot CLI

copilot plugin marketplace add DietrichGebert/ponytail
copilot plugin install ponytail@ponytail

In an interactive Copilot CLI session, use the slash equivalents:

/plugin marketplace add DietrichGebert/ponytail
/plugin install ponytail@ponytail

Copilot CLI namespaces plugin commands by plugin name. For example:

/ponytail:ponytail ultra
/ponytail:ponytail-review

Pi agent harness

pi install git:github.com/DietrichGebert/ponytail

OpenCode

Add to opencode.json:

{ "plugin": ["@dietrichgebert/ponytail"] }

Run from a checkout instead (the plugin reuses hooks/ and skills/):

{ "plugin": ["./.opencode/plugins/ponytail.mjs"] }

Injects the ruleset every turn at the active level; adds the /ponytail commands (see Commands). OpenCode also auto-loads this repo's AGENTS.md, so the rules hold even without the plugin. The plugin adds the lite/full/ultra/off levels.

The ./ path resolves against your project's opencode.json; to share one checkout across projects, point it at the absolute path of the .mjs instead (it finds its hooks/ and skills/ relative to its own file).

Gemini CLI

gemini extensions install https://github.com/DietrichGebert/ponytail

Loads the ruleset as always-on context every session and registers the /ponytail commands; the skills/ ship too, activated when a task needs them. The Gemini adapter intentionally does not ship a root hooks/hooks.json: Gemini auto-loads that path, while Ponytail's lifecycle hooks use Claude/Codex event names.

Qoder

Qoder auto-loads AGENTS.md from the repo root as always-on context, so running ponytail from a checkout works with zero setup. For per-project rules, copy .qoder/rules/ponytail.md into your project's .qoder/rules/. The six ponytail skills (/ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain, /ponytail-help) are available via Qoder's Skill system; the plugin manifest at .qoder-plugin/plugin.json points at the skills/ directory.

For full plugin-tier support (automatic mode activation + ruleset injection on every prompt), add the hooks from hooks/qoder-hooks.json to your .qoder/settings.json. Replace PONYTAIL_DIR with the path to your ponytail checkout. Qoder's UserPromptSubmit hook activates the default mode on first prompt and injects the ruleset every turn; PreToolUse with task|Task matcher injects the ruleset into subagents. Level switches (/ponytail lite|full|ultra|off) work automatically.

Antigravity CLI

Google is renaming Gemini CLI to Antigravity CLI (the agy binary); the same extension installs there:

agy plugin install https://github.com/DietrichGebert/ponytail

It reuses this repo's gemini-extension.json. One difference: Antigravity converts the /ponytail commands into skills, so you type them into the chat (e.g. /ponytail-review as a message) instead of picking them from a slash menu. Until the migration completes (around June 18, 2026), gemini extensions install still works too. To run it as an always-on rule instead, drop the ruleset into .agents/rules/.

Hermes Agent

hermes plugins install DietrichGebert/ponytail --enable

Restart Hermes after installing. The plugin injects the active Ponytail mode before each LLM turn, registers the bundled skills as ponytail:<skill>, and adds /ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain, and /ponytail-help. In shared gateways, restrict /ponytail to trusted users with Hermes slash-command access controls; runtime mode is process-local.

CodeWhale

Reads AGENTS.md from the project root, zero setup. Copy AGENTS.md to your project, or run codewhale from a checkout of this repo. That's it.

Swival

Stage the collection in your library first, then add the skills you want:

swival skills add --global https://github.com/DietrichGebert/ponytail  # stage into ~/.config/swival/library
swival skills add ponytail                                             # install the collection into this project
swival skills add --global ponytail                                    # or activate it in every project

Swival also reads AGENTS.md from the project root and ~/.config/swival/AGENTS.md globally, the instruction-only fallback.

On the command line, use a $ prefix to explicitly activate a skill. For example: $ponytail-review.

Devin CLI

devin plugins install DietrichGebert/ponytail

Installs ponytail as a Devin plugin; skills are available as /ponytail:ponytail, /ponytail:ponytail-review, and so on.

OpenClaw

clawhub install ponytail

Installs ponytail as an OpenClaw skill from ClawHub; the review, audit, debt, gain, and help skills install the same way (clawhub install ponytail-review, and so on). OpenClaw applies it on coding tasks and also exposes it as a /ponytail command. Without ClawHub, copy .openclaw/skills/ponytail into ~/.openclaw/skills/.

Grok Build

grok plugin install DietrichGebert/ponytail --trust

Enable the plugin (off by default): /plugins → Plugins → Space on ponytail, or in ~/.grok/config.toml:

[plugins]
enabled = ["ponytail"]

Start a new session (or reload plugins). Skills show as /ponytail, /ponytail-review, /ponytail-audit, /ponytail-debt, /ponytail-gain, /ponytail-help. Verify with grok inspect. Grok can auto-invoke ponytail for coding tasks from its skill description; use /ponytail (or /ponytail lite, /ponytail full, /ponytail ultra) when activation needs to be explicit. Grok lifecycle hooks are not used because their SessionStart output cannot inject instructions.

AGENTS.md still works instruction-only from a checkout without the plugin.

That was it. He'd be proud. He won't say it.

Active every session, with a handful of commands (see Commands). /ponytail ultra exists for when the codebase has wronged you personally. Startup and mode-change text shows the current mode.

Set the level for every new session with the PONYTAIL_DEFAULT_MODE env var (lite/full/ultra/off), or a defaultMode field in ~/.config/ponytail/config.json (%APPDATA%\ponytail\config.json on Windows). The default is full.

While active, the ruleset is also injected into every subagent spawned via the Agent tool. To scope that to specific agent types (say, keep it off read-only search agents), set the PONYTAIL_SUBAGENT_MATCHER env var to a regex tested against the subagent's agent_type. It is unanchored and case-insensitive: explore|general matches either, ^general$ is exact, and plugin agent types look like plugin:name. Unset means inject into every subagent (the default); an invalid regex, or a subagent whose type the platform doesn't report, also falls back to injecting.

Cursor, Windsurf, Cline, GitHub Copilot Chat (the VS Code, JetBrains, and Visual Studio editor extension, not the standalone Copilot CLI covered under Install), Aider, Kiro, Zed, CodeWhale, Swival, Qoder: copy the matching rules file from this repo (.cursor/rules/, .windsurf/rules/, .clinerules/, .github/copilot-instructions.md, AGENTS.md, .kiro/steering/, .qoder/rules/).

Kiro: copy .kiro/steering/ponytail.md to ~/.kiro/steering/ (global) or .kiro/steering/ in your project.

GitHub Copilot CLI fallback (instruction-only mode): it reads AGENTS.md and .github/copilot-instructions.md in a project, or copy the rules into ~/.copilot/copilot-instructions.md to run ponytail in every project. This path keeps always-on guidance, but does not add plugin mode switches or hooks.

VS Code with the Codex extension reads AGENTS.md, which this repo ships, so it works from the repo root with no setup (~/.codex/AGENTS.md makes Codex global).

JetBrains Junie can read AGENTS.md once you point it there in Settings → Tools → Junie → Project Settings → Guidelines Path (it is not automatic yet). This repo ships AGENTS.md; .junie/guidelines.md is Junie's legacy path.

Amp (Sourcegraph) reads AGENTS.md from the working directory and parent directories up to $HOME, which this repo ships, so it works with no setup (~/.config/amp/AGENTS.md works globally).

Jules (Google) reads AGENTS.md from the repository root, which this repo ships, so it picks up the ruleset with no setup.

Which files map to which agent: Agent portability.

Uninstall

Host	Command
Claude Code	`/plugin remove ponytail`
Codex	`codex plugin remove ponytail`
Devin CLI	`devin plugins remove ponytail`
Grok Build	`grok plugin uninstall ponytail`
Pi agent	`pi uninstall ponytail`
Cursor / Windsurf / Cline / Qoder / etc.	Delete the copied rule file

These remove the plugin's own files. They leave behind a small amount of state ponytail writes outside the plugin folder: the mode flag, ~/.config/ponytail/config.json, and (if you accepted the setup nudge) a statusLine entry in ~/.claude/settings.json. Run node scripts/uninstall.js to clean those up too. Run it before the host remove command above — the script is itself a plugin file, so removing the plugin first deletes it (or run it from a separate clone of this repo). It only removes the statusLine entry if it points at ponytail's own script, so a statusline you set up yourself is left untouched.

Commands

Command	What it does
`/ponytail [lite \| full \| ultra \| off]`	Set the intensity, or turn it off. No argument reports the current level.
`/ponytail-review`	Review the current diff for over-engineering, hands back a delete-list.
`/ponytail-audit`	Audit the whole repo for over-engineering, not just the diff.
`/ponytail-debt`	Harvest the `ponytail:` shortcuts you've deferred into a ledger, so "later" doesn't become "never".
`/ponytail-gain`	Show the measured impact scoreboard (less code, less cost, more speed) from the benchmark.
`/ponytail-help`	Quick reference for the commands above.

Commands need a skill-capable host (Claude Code, Codex, Devin CLI, OpenCode, Gemini, pi, Swival, Hermes Agent, Qoder, Grok Build). In Codex they're skills, invoke with @ (@ponytail-review). The instruction-only adapters (Cursor, Windsurf, Cline, Copilot, Kiro, Antigravity) load the always-on ruleset without the commands.

Development

When changing the compact rule text, keep the agent copies aligned:

node scripts/check-rule-copies.js
npm test

The OpenClaw skill package (.openclaw/skills/) is generated from skills/; rerun node scripts/build-openclaw-skills.js after changing a skill, the test suite fails if it is stale. To publish the skills to ClawHub, run clawhub login once, then node scripts/publish-openclaw-skills.js (it publishes all six at the package.json version; pass --dry-run to preview).

The correctness benchmark spawns Python for email and CSV checks; python3 is tried before python. CSV checks need pandas installed locally.

FAQ

Can I use it with caveman? Yes, and you should. Caveman shrinks what the agent says; ponytail shrinks what it builds. Different halves, no overlap: caveman leaves code byte-for-byte exact, ponytail stays out of the prose. Terse talk about minimal code.

Does it need a config file? No. An optional ~/.config/ponytail/config.json or PONYTAIL_DEFAULT_MODE env var can set the default level, but nothing is required.

What if I really need the 120-line cache class? You don't. Insist anyway and he'll build it. Slowly. Correctly. While looking at you.

Does it scale? The code you never wrote scales infinitely. Zero bugs, zero CVEs, 100% uptime since forever.

Why "ponytail"? You know exactly why.

License

MIT. The shortest license that works.

Star History

polius/FileSync

Send files from one device to many in real-time.

FileSync

Send files from one device to many, in real time — private, peer-to-peer, with no size limit.

Features

🔒 Private by design — files travel directly between browsers over encrypted WebRTC. The server only brokers the initial handshake; it never sees your file contents.
🚀 No size limit — received files stream straight to disk, so even multi-gigabyte transfers use almost no memory (over HTTPS — see how files are saved).
👥 One-to-many — share a room link or QR code and send to as many devices at once.
🌐 Works across networks — connects directly when possible, with automatic STUN/TURN relay fallback for restrictive NATs and firewalls.
🪄 No installs, no accounts — recipients just open a link in any modern browser. Optional password protection per room.
🐳 Self-hosted — a single Docker image you run yourself.

How to use

Open your FileSync URL — you land in a room with a unique link and a QR code.
Share the link (or QR) with the people or devices you want to send to.
Drop in your files — drag and drop them (or click Send Files). Recipients see them appear and can download instantly.

Want to restrict access? Click Add password to protect the room before sharing the link.

Self-hosting

Prerequisites

Docker and Docker Compose
Python 3 (only to generate the secret key below)

Every deployment needs a secret key (it signs the TURN credentials used for NAT traversal). Generate one with:

python3 -c "import secrets, base64; print(base64.b64encode(secrets.token_bytes(32)).decode())"

⚠️ Use your own generated value — never ship the examples shown below.

Option A — HTTP (local network / quick start)

Best for trying FileSync or running it on a trusted LAN. Note that large transfers (>~500 MB) are unreliable over plain HTTP — for those, use Option B.

1. Download deploy/docker-compose.yml.

2. Set your secret. Replace both <SECRET_KEY> placeholders with your generated value:

# (use your own generated value — these are illustrative)
- --static-auth-secret=Hs9k…your-generated-key…=
- SECRET_KEY=Hs9k…your-generated-key…=

3. Start it:

docker compose up -d

Open http://localhost (or your server's IP).

Option B — HTTPS (public domain, recommended)

Caddy obtains and renews a Let's Encrypt certificate automatically. HTTPS also unlocks memory-safe streaming for files of any size.

1. Download deploy/docker-compose-ssl.yml and deploy/Caddyfile.

2. Set your secret. Replace both <SECRET_KEY> placeholders (same as Option A).

3. Set your domain. In Caddyfile, replace yourdomain.com with your domain:

filesync.example.com {
    reverse_proxy filesync:80
}

4. Start it:

docker compose -f docker-compose-ssl.yml up -d

Open https://yourdomain.com.

Stopping FileSync

docker compose down                          # HTTP setup
docker compose -f docker-compose-ssl.yml down  # HTTPS setup

Required ports

Open these on your server/firewall to expose FileSync to the internet:

Port	Protocol	Purpose
`80` (HTTP) / `443` (HTTPS)	TCP	Web interface
`3478`	TCP + UDP	STUN/TURN — peer-to-peer connection setup
`50000–50100`	UDP	TURN relay range — used when a direct connection isn't possible

Port 3478 handles connection setup. The 50000–50100 UDP range carries relayed traffic for the ~5–10% of connections that can't go direct (typically a peer behind symmetric NAT or a UDP-blocking firewall).

Customizing ports

HTTP port. In docker-compose.yml, change the first number of the filesync port mapping (the second is the internal container port — leave it as 80):

ports:
  - "8080:80"   # serve on http://localhost:8080

HTTPS port. Keep Caddy on 443 and put your own reverse proxy (Nginx, Traefik, standalone Caddy) in front if you need a non-standard external port — terminate TLS there and forward to FileSync's internal HTTP port.

Configuration

Environment variables on the filesync service:

Variable	Required	Default	Description
`SECRET_KEY`	Yes	—	Signs TURN credentials and tokens. Must match the coturn `--static-auth-secret`. The app won't start without it.

How received files are saved

FileSync writes received files to disk as the bytes arrive, so transfers use almost no memory regardless of size. It uses the first method the browser supports, falling back in order:

File System Access API — streams straight to a file you pick. Desktop Chromium browsers (Chrome, Edge, Brave, Opera) over HTTPS.
Service Worker — streams into a normal browser download. All modern browsers over HTTPS.
Blob — buffers the whole file in memory, then saves it. Last resort; the only option over plain HTTP, and unreliable past ~500 MB.

The first two require a secure context (HTTPS, or localhost), so serving FileSync over HTTPS is recommended — it enables memory-safe transfers of any size.

Under the hood

FileSync uses native WebRTC to transfer files directly between devices — peer-to-peer, with no intermediate server in the data path. Your files stay private throughout.

A lightweight WebSocket signaling server (served at /ws by the FileSync app itself) assists only with the initial connection setup — relaying SDP offers/answers and ICE candidates between peers. Once a peer-to-peer connection is established, the signaling server steps back and file bytes flow directly between browsers. The server never has access to file contents.

License

Released under the MIT License.

cobusgreyling/loop-engineering

Practical patterns, starters & CLI tools for loop engineering with AI coding agents. Design systems that prompt and orchestrate agents (inspired by Addy Osmani and Boris Cherny). Includes loop-audit, loop-init, loop-cost.

Loop Engineering

Stop prompting. Design the loop. Get a score.

# Front door (recommended) — one binary for init + doctor + status
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok
npx @cobusgreyling/loop doctor .

# Same as before (still fully supported — forks need not change)
npx @cobusgreyling/loop-init .
# Optional: also scaffold a versioned harness (harness-foundry)
npx @cobusgreyling/loop init . --with-foundry

loop init (or loop-init) scaffolds skills, state, and budget files, then prints your Loop Ready score and first loop command. loop doctor combines audit + sync + file checks into top-3 next actions. Swap --tool for claude, codex, or opencode. Use --with-foundry when you want the loop as a composable runtime stack. See docs/cli-front-door.md.

Loop engineering replaces you as the person who prompts the agent — you design the system that does it instead.

New here? Quickstart (5 min) · Interactive picker

For developers using Grok, Claude Code, Codex, Cursor, and other AI coding agents.

→ Interactive showcase + pattern picker · Essay · Addy Osmani

Quick Links

Start here	Description
Quickstart (5 min)	`loop init` → `loop doctor` → first loop — start here if you just landed
CLI front door	Unified `@cobusgreyling/loop` — old packages stay open
Loop Engineering essay	The concept, primitives, and Grok mapping — read for the why
Pattern Picker	Which loop to run first — start here if unsure
Primitives Matrix	Cross-tool loop primitive mapping — bookmark this
Loop Design Checklist	Ship readiness rubric
Patterns	7 production patterns + interactive picker
Starters	Clone-and-run kits (Grok, Claude Code, Codex, Opencode)
Opencode examples	CLI-first loops: cron/systemd + `opencode run`, skills, worktrees
loop (front door)	Unified CLI — `npx @cobusgreyling/loop init \| doctor \| status \| audit \| cost` · cli-front-door
loop-audit	Loop Readiness Score CLI (v1.7 — constraints + governance + Harness Runtime) — `npx @cobusgreyling/loop audit . --suggest` · also `loop-audit`
loop-init	Scaffold starters + budget/run-log + constraints (v1.5) — `npx @cobusgreyling/loop init . --pattern daily-triage --tool grok` · also `loop-init`
harness-foundry	Companion runtime: versioned stacks, sessions, traces — `npx @cobusgreyling/harness-foundry init --from loop-engineering:daily-triage`
outerloop	Companion governance: evidence → verdict → answerability
loop-cost	Token spend estimator — `npx @cobusgreyling/loop-cost`
loop-sync	Drift detection between `STATE.md` and `LOOP.md` — `npx @cobusgreyling/loop-sync .`
loop-context	Stateful memory manager + circuit breaker for long runs — `npx @cobusgreyling/loop-context --check --ledger run.json`
loop-mcp-server	MCP runtime lookup for patterns, skills, state — `npx @cobusgreyling/loop-mcp-server`
loop-worktree	Manage isolated git worktrees per fix attempt — `npx @cobusgreyling/loop-worktree create --run-id <id> --pattern <p>`
loop-gate	Mechanical enforcement of the path denylist + auto-merge allowlist from `gate.yaml` — `npx @cobusgreyling/loop-gate check --action auto-merge --paths <f1,f2,...>`
loop-sandbox	Ephemeral git worktree isolation + patch capture — `npx @cobusgreyling/loop-sandbox run -- <cmd>`
loop-action	GitHub Composite Action for running loops in CI — `uses: cobusgreyling/loop-engineering/tools/loop-action@main`
Goal Engineering	Companion: loops discover, goals finish — `/goal` + stack cookbook (`npx @cobusgreyling/goal doctor .`)
Memory Engineering	Companion: stop re-explaining the repo — tiers, budget, Memory Ready score (`node tools/memory-init/cli.js .`)
Fleet Engineering	Companion: govern populations of agents — registry, inbox, Fleet Ready score (`npx @cobusgreyling/fleet-init .`)
Stories	Real wins and honest failures

Ecosystem stack

memory-engineering → loop-engineering → harness-foundry → outerloop → fleet-engineering
   (persist)            (patterns)         (runtime)        (verdict)     (population)

Layer	You get	Start
Memory	Tiers, recall budget, Memory Ready score	memory-engineering
Design (this repo)	Patterns, starters, Loop Ready score	`npx @cobusgreyling/loop init .` then `loop doctor .`
Runtime	Versioned harness, traces, evolve	`npx @cobusgreyling/loop init . --with-foundry` or Foundry showcase
Govern	Evidence, verdict, answerability	outerloop
Fleet	Registry, inbox, budgets, kill switch	`npx @cobusgreyling/fleet-init .` · Fleet Ready

Scale beyond one loop: when agents forget across sessions, add memory-engineering. When you have many agents/loops on a team, add fleet-engineering.

Next after Loop Ready 80+: version the loop as a harness — loop-init prints the CTA automatically; loop-audit recommends Foundry when the score is strong but .foundry/stack.yaml is missing.

Community & announcements

Discussion	Summary
Contributor quickstart	Help wanted: open `good first issues` — comment I'll take this to get assigned · see Help wanted
Community update	July 4: 5.5k stars, traffic sources, contributor merges
Community week (Jul 8)	loop-worktree npm, MCP quickstart, tool appendices
npm update (Jul 16)	`loop-context` 1.2.0 + `loop-worktree` 1.1.0 — daily budget, path locks
Maintenance (Jul 10)	Doc sync, branch prune, loop-audit 1.6.0 follow-up
Prior release notes	v1.5.0 — loop-sync, constraints, MCP server
Add your project	Pinned: Loop Ready badge + adopters list

Why This Matters

Peter Steinberger:

“You shouldn’t be prompting coding agents anymore. You should be designing loops that prompt your agents.”

Boris Cherny (Head of Claude Code at Anthropic):

“I don’t prompt Claude anymore. I have loops running that prompt Claude and figuring out what to do. My job is to write loops.”

The leverage point has moved from crafting individual prompts to designing the control systems that orchestrate agents over time.

The Five Building Blocks + Memory

Primitive	Job in the Loop
Automations / Scheduling	Discovery + triage on a cadence
Worktrees	Safe parallel execution
Skills	Persistent project knowledge
Plugins & Connectors	Reach into your real tools (MCP)
Sub-agents	Maker / checker split
+ Memory / State	Durable spine outside any conversation

Full detail: docs/primitives.md · Cross-tool matrix: docs/primitives-matrix.md

Visual Overview

Anatomy of a Loop

Mermaid diagram (copy-friendly)

flowchart LR
    A[Schedule / Automation] --> B[Triage Skill]
    B --> C[Read + Write STATE / Memory]
    C --> D[Isolated Worktree]
    D --> E[Implementer Sub-agent]
    E --> F[Verifier Sub-agent<br/>tests + gates]
    F --> G[MCP / Git / Tickets]
    G --> H{Human Gate?}
    H -->|safe / allowlisted| I[Commit / PR / Action]
    H -->|risky / ambiguous| J[Escalate to human<br/>with full context]
    I --> A
    J --> A

Deeper diagrams — the actor-level sequence within one run, the run lifecycle's states, autonomy levels L1-L3, and how tools/ maps onto the primitives — live in docs/architecture-diagrams.md.

This reference repo now runs its own validate-patterns + audit workflows on every push/PR (see .github/workflows/). We also added LOOP.md describing the loops that will maintain it.

Patterns

Pattern	Cadence	Starter	Week 1	Token cost
Daily Triage	1d–2h	minimal-loop	L1 report	Low
PR Babysitter	5–15m	pr-babysitter	L1 watch	High
CI Sweeper	5–15m	ci-sweeper	L2 cautious	Very high
Dependency Sweeper	6h–1d	dependency-sweeper	L2 patch-only	Medium
Changelog Drafter	1d or tag	changelog-drafter	L1 draft	Low
Post-Merge Cleanup	1d–6h	post-merge-cleanup	L1 off-peak	Low
Issue Triage	2h–1d	issue-triage	L1 propose-only	Low

Not sure which to pick? Try the interactive picker or pattern-picker.

Machine-readable index: patterns/registry.yaml (7 patterns)

Getting Started (5 minutes)

# 1. Scaffold + Loop Ready score (printed automatically)
npx @cobusgreyling/loop init . --pattern daily-triage --tool grok

# 2. One health check (audit + sync + files → top 3 actions)
npx @cobusgreyling/loop doctor .

# 3. Optional: cost estimate / badge / day-2 dashboard
npx @cobusgreyling/loop cost --pattern daily-triage --level L1
npx @cobusgreyling/loop badge .
npx @cobusgreyling/loop status .

# 4. See scores climb: empty → L1 → L2
bash scripts/before-after-demo.sh

# 5. Start report-only (Grok example)
/loop 1d Run loop-triage. Update STATE.md. No auto-fix in week one.

Same as before: npx @cobusgreyling/loop-init and loop-audit still work — CLI front door.

All npm CLIs publish from tagged releases — see docs/RELEASE.md. No clone required.

Develop from source (monorepo contributors):

cd tools/loop && npm ci && npm test && node dist/cli.js doctor ../..
cd tools/loop-init && npm ci && npm test && node dist/cli.js /path/to/project --pattern daily-triage --tool grok
cd tools/loop-audit && npm ci && npm test && node dist/cli.js /path/to/project --suggest
cd tools/loop-cost && npm ci && npm test && node dist/cli.js --pattern ci-sweeper --cadence 15m

Phased rollout: L1 report → L2 assisted fixes → L3 unattended — see loop-design-checklist.

Examples by Tool

Operating & Safety

Failure Modes — incident-style catalog
Anti-Patterns — design mistakes before production
Multi-Loop Coordination — when loops collide
Operating Loops — cost, logging, when to kill
Safety — denylist, auto-merge, MCP scopes
Security — reporting and unattended automation risks
Concepts — intent debt, comprehension debt, harness vs loop
MCP Cookbook — connector examples by pattern

Caveats

Loop engineering amplifies judgment — both good and bad.

Token costs can explode with sub-agents and long-running loops.
Verification is still on you. Unattended loops make unattended mistakes.
Comprehension debt grows faster unless you read what the loop ships.
Two people can run the same loop and get opposite results. The loop doesn't know. You do.

Addy Osmani:

“Build the loop. But build it like someone who intends to stay the engineer, not just the person who presses go.”

Help wanted

First PR? Pick one open issue below. Stories and adopters get same-day review when possible. See CONTRIBUTORS.md and the contributor quickstart.

12 open good first issues (refreshed 2026-08-10 — Wave 6 from real community PR pain). Comment "I'll take this" for assignment.

Time	Issue	What you ship
~10 min	#120 — Adopters list	One row in `docs/adopters.md` (or Add Adopter template)
~15–20 min	#118 — Daily Triage story · #173 — Issue Triage story · #119 — PR Babysitter failure	Honest `stories/` write-up + index row
~20–25 min	#483 — Windows notes	Windows/CRLF landing notes in QUICKSTART (pain from #476)
~20–40 min	#481 — append-run-log JSON test · #480 — skill-dedup test · #479 — loop-sync CRLF tests	Regression tests locking fixes from #474–#476
~40–45 min	#387 — Hermes CI Sweeper · #388 — Hermes Issue Triage · #484 — Windsurf Post-Merge · #485 — Windsurf Changelog	Fill pattern-coverage gaps in `examples/`
Anytime	Templates	Add Adopter · Share a story
Hubs	Discussions	Show your loop · Ask anything

Recently shipped (thanks!): Community batch from @pxmpsdev — goal-audit fixture + run-log guard (#474), readiness-core skill dedup (#475), loop-sync CRLF (#476), root npm ci docs (#477). Earlier: Windsurf examples, loop-action/sandbox/gate QUICKSTART, CI Sweeper story.

Docs/examples triage: @AIMindCrafter co-owns docs/, examples/, and stories/ (see CODEOWNERS + docs/area-owners.md).

Maintainers re-seed the backlog with bash scripts/create-good-first-issues.sh (idempotent; skips existing titles). Prefer live open GFI filter over this table if a row looks stale.

Contributing

Share production patterns, tool mappings, and failure stories. See CONTRIBUTING.md (contribution ladder + good first issue backlog), Code of Conduct, adopters, and hubs: Show your loop · Ask anything.

Sources

License

MIT

Practical, tool-aware reference for loop engineering, patterns you can clone, checklists you can ship against, and stories that include what broke.

Essay · Showcase · Cobus Greyling

_{Static chart (CI-updated daily). Live chart needs a GitHub token — stored in your browser only.}

plankanban/planka

PLANKA is the Kanban-style project mastering tool for everyone

PLANKA

Project mastering driven by fun

Install · Demo · Docs · API · Cloud · Pro version

Key Features

Collaborative Kanban Boards: Create projects, boards, lists, cards, and manage tasks with an intuitive drag-and-drop interface
Real-Time Updates: Instant syncing across all users, no refresh needed
Rich Markdown Support: Write beautifully formatted card descriptions with a powerful markdown editor
Flexible Notifications: Get alerts through 100+ providers, fully customizable to your workflow
Multilingual & Easy to Translate: Full internationalization support for a global audience

How to Deploy

PLANKA is easy to install using multiple methods - learn more in the installation guide.

For configuration and environment settings, see the configuration section.

Interested in a hosted or Pro version of PLANKA? Check out the pricing on our website.

Notes App

A testing version of the Notes app is now available on multiple platforms:

iOS: Join the TestFlight to try the app
Windows & Android: Download the app here

Contact

For any security issues, please do not create a public issue on GitHub - instead, report it privately by emailing security@planka.group.

Note: We do NOT offer any public support via email, please use GitHub.

Join our community: Get help, share ideas, or contribute on our Discord server.

License

PLANKA is fair-code distributed under the Fair Use License and PLANKA Pro/Enterprise License.

Source Available: The source code is always visible
Self-Hostable: Deploy and host it anywhere
Extensible: Customize with your own functionality
Enterprise Licenses: Available for additional features and support

For more details, check the License Guide.

Contributing

Found a bug or have a feature request? Check out our Contributing Guide to get started.

For setting up the project locally, see the development section.

Thanks to all our contributors!

lodash/lodash

A modern JavaScript utility library delivering modularity, performance, & extras.

lodash v4.18.1

Important

As announced on the OpenJS Foundation blog, Lodash has received support from the Sovereign Tech Agency and will transition to the Feature-Complete maturity stage so that it remains stable, secure, and sustainable long-term. As part of this effort, Lodash is rebooting its governance. A draft charter will be published shortly. The upcoming Technical Steering Committee (TSC) is already at work. For transparency, its members are listed in GOVERNANCE.md.

The Lodash library exported as a UMD module.

Generated using lodash-cli:

$ npm run build
$ lodash -o ./dist/lodash.js
$ lodash core -o ./dist/lodash.core.js

Download

Lodash is released under the MIT license & supports modern environments.
Review the build differences & pick one that’s right for you.

Installation

In a browser:

<script src="lodash.js"></script>

Using npm:

$ npm i -g npm
$ npm i --save lodash

In Node.js:

// Load the full build.
var _ = require('lodash');
// Load the core build.
var _ = require('lodash/core');
// Load the FP build for immutable auto-curried iteratee-first data-last methods.
var fp = require('lodash/fp');

// Load method categories.
var array = require('lodash/array');
var object = require('lodash/fp/object');

// Cherry-pick methods for smaller browserify/rollup/webpack bundles.
var at = require('lodash/at');
var curryN = require('lodash/fp/curryN');

Why Lodash?

Lodash makes JavaScript easier by taking the hassle out of working with arrays,
numbers, objects, strings, etc. Lodash’s modular methods are great for:

Iterating arrays, objects, & strings
Manipulating & testing values
Creating composite functions

Module Formats

Lodash is available in a variety of builds & module formats.

affaan-m/ECC

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

Warning

Official sources only. Install ECC only from verified channels: the GitHub repository github.com/affaan-m/ECC, the npm packages ecc-universal and ecc-agentshield, the GitHub App, the plugin slug ecc@ecc, and the project website ecc.tools. Third-party re-uploads and unofficial mirrors are not maintained or reviewed by the project and may contain malware.

Install with Claude Code

Run these commands inside Claude Code:

/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc

That installs ECC's skills, agents, commands, and plugin-managed hooks. If you choose this path, stop there. Do not also run a full manual install into Claude Code.

Guided package setup is coming in ecc-universal 2.2.0. Use the native Claude plugin commands above while npm remains on 2.1.0.

ECC Pro + GitHub App
_{Install free · Private repos from $19/seat/mo}

Sponsor ECC
_{Fund the open-source project}

Community
_{Discord · Q&A · Show and Tell}

_{OSS stays free. This repo is MIT-licensed forever. ECC Pro is the hosted GitHub App for private repos. Sponsors and Pro subscribers fund the work. That's why a single maintainer ships weekly across 7 harnesses.}

_{Partners & sponsors}

_{Community sponsors: Mike Morgan · @jasonwu513 · @1anter · @massimotodaro · @meadmccabe}

_{Become a Sponsor · Sponsor Tiers · Sponsorship Program}

Jump to install ↓

ECC

Your agent can write code, but ECC gives it a coordinated engineering system and toolbox: it plans before it builds, verifies changes with tests, reviews its own work from a fresh context, remembers what matters, and turns repeated wins into reusable skills and workflows.

plan -> test -> implement -> review -> verify -> remember -> improve

Instead of rebuilding that process in every prompt, you install it once and make it part of how your agent works.

Optimize the context window. Persist everything else.

ECC is MIT-licensed open source. It works best with Claude Code today, has a supported Codex sync path, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. See the support status matrix before assuming feature parity.

Access to 68 agents, 287 skills, and 94 legacy command shims, plus hooks, rules, memory, continuous learning, and AgentShield security scanning. The agents are specialized for planning, review, build repair, security, architecture, and domain work.

Included	Count	What it gives you
Agents	68 agents	Planning, review, build repair, security, architecture, and domain work
Skills	287 skills	TDD, research, security, docs, frontend, data, ML, operations, and more
Commands	94 commands	Convenient entry points while ECC moves to a skills-first surface
Hooks and memory	Runtime	Enforcement, session summaries, continuous learning, instincts, and context controls
Rules	Selective	Always-loaded standards you choose by language or project
AgentShield	Included	Scanning for prompts, hooks, MCP config, permissions, secrets, and agent files

Install ECC

Important

Guided package setup is coming in ecc-universal 2.2.0. The current npm release, 2.1.0, does not include the guided setup commands. Use the native Claude plugin commands at the top of this README until 2.2.0 is published.

Pick one path only (per harness)

You can use ECC with Claude Code, Codex, and other harnesses at the same time. Choose one install method for each harness:

Recommended today for Claude Code: use the native plugin commands above
Coming in release 2.2: guided package setup for Claude Code, Codex, and Kimi Code; see the preview at the bottom of this install area
Works: Claude Code plugin + Codex native plugin
Works: Claude Code plugin + the legacy Codex sync flow
Avoid: Claude Code plugin + full Claude manual install
Avoid: Codex sync + Codex marketplace plugin

Do not stack install methods. Installing ECC twice into the same harness can duplicate skills, commands, hooks, or configuration; installing it once into multiple harnesses does not.

If you already layered multiple installs and things look duplicated, skip straight to Reset / Uninstall ECC.

Install trouble? Open the short install or runtime problem form, or run ecc feedback. ECC never uploads diagnostics automatically.

Claude Code details

Claude Code owns these built-in commands, including their errors when a marketplace, plugin, or conflicting scope already exists. ECC cannot intercept that parser. If either native command reports an existing install or scope conflict, wait for the 2.2.0 guided setup or resolve the conflicting Claude plugin scope before retrying; do not layer a manual install on top.

After ECC is installed, /ecc:configure-ecc is the namespaced in-Claude reconfiguration skill. It delegates to the same safe setup flow, but it is available only after the plugin is installed and cannot replace Claude Code's built-in /plugin command during a first install.

Claude Code plugins cannot distribute rules, so add only the rule packs you actually want:

git clone https://github.com/affaan-m/ECC.git
cd ECC
mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/  # replace with your stack

Start with rules/common plus one language or framework pack you actually use. If you install the plugin, do not run ./install.sh --profile full afterward.

Prefer settings.json? Add the marketplace declaratively

Add directly to your ~/.claude/settings.json:

{
  "extraKnownMarketplaces": {
    "ecc": {
      "source": {
        "source": "github",
        "repo": "affaan-m/ECC"
      }
    }
  },
  "enabledPlugins": {
    "ecc@ecc": true
  }
}

This gives you the same result as the two /plugin commands above.

Naming + migration note (ecc@ecc, affaan-m/ECC, ecc-universal)

ECC has three public identifiers, and they are not interchangeable:

GitHub source repo: affaan-m/ECC
Claude marketplace/plugin identifier: ecc@ecc
npm package: ecc-universal

This is intentional. Anthropic marketplace/plugin installs are keyed by a canonical plugin identifier, so ECC uses ecc@ecc to keep tool names and slash-command namespaces short enough for strict Desktop/API validators. Older posts may still show the former long marketplace identifier; treat that as a legacy alias only. Separately, the npm package stayed on ecc-universal, so npm installs and marketplace installs intentionally use different names.

npm releases are cut per version tag, not per commit, so ecc-universal tracks releases (2.1, 2.2, ...) rather than every push to main. Install from git if you want the bleeding edge.

If your local Claude setup was wiped or reset, that does not mean you need to repurchase anything. Start with node scripts/ecc.js list-installed, then run node scripts/ecc.js doctor and node scripts/ecc.js repair before reinstalling. That usually restores ECC-managed files without rebuilding your setup.

Codex App and CLI

Current Codex releases can install ECC as a native repo-marketplace plugin. The marketplace entry uses the repository root so Codex's cache receives the manifest together with all referenced skills, MCP configuration, hook runtime, scripts, and assets:

codex plugin marketplace add affaan-m/ECC
codex plugin add ecc@ecc
codex plugin list --json
node scripts/codex/check-plugin-cache.js

Both add commands are idempotent. To refresh later, run codex plugin marketplace upgrade ecc followed by codex plugin add ecc@ecc. Codex stores one enabled plugin state in the active CODEX_HOME; it does not offer Claude's user, project, and local scopes. Its native hooks require an explicit trust decision and do not use Claude's four ECC hook profiles. Inside Codex, invoke $configure-ecc for the guided provider-aware flow.

The older scripts/sync-ecc-to-codex.sh path remains a separate compatibility option for users who intentionally want copied and merged configuration in ~/.codex; it is not required for the native plugin. Run Codex once first so ~/.codex/config.toml exists, then:

git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install
bash scripts/sync-ecc-to-codex.sh

You can also open the ECC repository directly in Codex for a project-local setup. Codex reads the root AGENTS.md and the trusted project configuration in .codex/ without a global sync. Do not add the native marketplace plugin on top of the sync flow.

For repo navigation, surface ownership, and PR diff packet guidance, read the Codex ECC Navigation Map. See the .codex plugin notes for native lifecycle details.

Other agents and editors

Cursor, OpenCode, Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode, Copilot

Clone ECC once, then choose the target that matches your harness:

git clone https://github.com/affaan-m/ECC.git
cd ECC

Harness	Install or setup	Notes
Cursor	`./install.sh --profile minimal --target cursor`	Project-local `.cursor/` adapter
OpenCode	`npm install && npm run build:opencode && ./install.sh --profile full --target opencode`	Builds the plugin payload before the full install
Gemini CLI	`./install.sh --profile minimal --target gemini`	Project-local `.gemini/` config
Zed	`./install.sh --profile minimal --target zed`	Project-local `.zed/` adapter
Antigravity	`./install.sh --profile minimal --target antigravity`	See the Antigravity guide
Qwen CLI	`./install.sh --profile minimal --target qwen`	See the Qwen guide
Hermes	`./install.sh --profile minimal --target hermes`	See the Hermes setup guide
OpenClaw	`./install.sh --profile minimal --target openclaw`	Managed home-directory install
Kimi Code CLI	`./install.sh --profile minimal --target kimi`	Project-local `.kimi-code/` install
CodeBuddy	`./install.sh --profile minimal --target codebuddy`	Project-local `.codebuddy/` install
JoyCode	`./install.sh --profile minimal --target joycode`	Project-local `.joycode/` install

GitHub Copilot support is already included in this repository. .github/copilot-instructions.md provides the instruction layer, .github/prompts/ contains the reusable /plan, /tdd, /security-review, /build-fix, and /refactor prompts, and .vscode/settings.json enables chat.promptFiles.

For a harness without a native ECC target, use the manual adaptation guide. It explains how to carry a small set of ECC skills and workflow instructions into chat-style tools without pretending hooks or native skill discovery are available.

Cursor installs agent definitions under .cursor/agents/ecc-*.md. Cursor-native loading behavior can vary by Cursor build. ECC does not install root AGENTS.md into .cursor/. The adapter keeps Cursor's context scoped to its native rules and agent surfaces.

Deep per-harness notes (feature parity, hook adapters, limitations) live in Platform Support below.

Advanced Install Options

The options stay here, directly under the main install paths, so you do not have to hunt through the README when the default setup is not the right fit.

Low-context install with no hook runtime

Low-context / no-hooks path

Use this when you want ECC's rules, agents, commands, platform config, and core workflows without runtime hooks:

./install.sh --profile minimal --target claude

Windows:

.\install.ps1 --profile minimal --target claude

This profile intentionally excludes hooks-runtime.

Claude manual installs place each skill directly under ~/.claude/skills/<skill-name>/ (or .claude/skills/<skill-name>/ for claude-project) so Claude Code can discover it. When upgrading an older ECC manual install, the installer migrates only nested skills/ecc/ files recorded in ECC install-state. If a flat skill directory is user-owned, ECC preserves it, prints a conflict warning, and keeps any older managed copy tracked for a safe uninstall instead of overwriting user files.

For the normal core profile with hooks disabled:

./install.sh --profile core --without baseline:hooks --target claude

Add the hook runtime later only if you want it:

./install.sh --target claude --modules hooks-runtime

Choose only the components you need

Find the right components first

Ask the packaged advisor which components match your work:

node scripts/ecc.js consult "security reviews" --target claude

It returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan.

You can also install explicit skills or capabilities:

./install.sh --target claude --skills tdd-workflow,security-review
node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning

Manual component-by-component copying also works. Each component is fully independent:

# Just agents
cp agents/*.md ~/.claude/agents/

# Rules directories (common + language-specific)
mkdir -p ~/.claude/rules/ecc
cp -r rules/common ~/.claude/rules/ecc/
cp -r rules/typescript ~/.claude/rules/ecc/   # pick your stack

# Core/general skills only (Claude Code loads skills from direct children
# of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/)
mkdir -p ~/.claude/skills
cp -r .agents/skills/* ~/.claude/skills/
cp -r skills/search-first ~/.claude/skills/

# Optional: maintained slash-command compatibility during migration
mkdir -p ~/.claude/commands
cp commands/*.md ~/.claude/commands/

Retired shims live in legacy-command-shims/. Copy individual files from there only if you still need old names such as /tdd.

Project-local rules instead of global rules

Use project-local rules when ECC's standards should apply to one repository rather than every Claude Code session:

cd your-project
mkdir -p .claude/rules/ecc
cp -R /path/to/ECC/rules/common .claude/rules/ecc/
cp -R /path/to/ECC/rules/typescript .claude/rules/ecc/

Rules are always-loaded context, so begin with common and one pack for the stack you actually use. When copying rules manually, copy the whole language directory (for example rules/common or rules/golang), not the files inside it, so relative references keep working and filenames do not collide.

Fully manual Claude install

Use this only when you are intentionally skipping the plugin path:

git clone https://github.com/affaan-m/ECC.git
cd ECC
./install.sh --profile full

Windows:

git clone https://github.com/affaan-m/ECC.git
cd ECC
.\install.ps1 --profile full

If you choose this path, stop there. Do not also run /plugin install.

For hand-picked manual installs, Claude discovers skills as direct children of ~/.claude/skills/; do not nest them under ~/.claude/skills/ecc/.

Install hooks

Do not copy the raw repo hooks/hooks.json into ~/.claude/settings.json or ~/.claude/hooks/hooks.json. That file is plugin/repo-oriented; use the installer so hook command paths are rewritten correctly:

bash ./install.sh --target claude --modules hooks-runtime

That writes resolved hooks to ~/.claude/hooks/hooks.json and leaves any existing ~/.claude/settings.json untouched.

If you installed ECC via /plugin install, do not copy those hooks into settings.json. Claude Code v2.1+ already auto-loads plugin hooks/hooks.json, and duplicating them in settings.json causes duplicate execution and cross-platform hook conflicts.

On Windows, Claude's config root is %USERPROFILE%\\.claude; install the hook runtime with:

pwsh -File .\install.ps1 --target claude --modules hooks-runtime

Configure MCPs

Claude plugin installs intentionally do not auto-enable ECC's bundled MCP server definitions. This avoids overlong plugin MCP tool names on strict third-party gateways while keeping manual MCP setup available.

Use Claude Code's /mcp command or CLI-managed MCP setup for live Claude Code server changes; Claude Code persists those choices in ~/.claude.json. For repo-local MCP access, copy desired MCP server definitions from mcp-configs/mcp-servers.json into a project-scoped .mcp.json.

ECC ships exactly one default connector (chrome-devtools); everything else is a skill wrapping a CLI/REST API or an opt-in catalog entry. The rule and the June 2026 audit that retired the previous six defaults live in docs/MCP-CONNECTOR-POLICY.md.

If you already run your own copies of ECC-bundled MCPs, set:

export ECC_DISABLED_MCPS="chrome-devtools"

ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates. ECC_DISABLED_MCPS is an ECC install/sync filter, not a live Claude Code toggle.

Important: Replace YOUR_*_HERE placeholders with your actual API keys.

Multi-model commands require additional setup

multi-* commands are not covered by the base plugin/rules install.

To use /multi-plan, /multi-execute, /multi-backend, /multi-frontend, and /multi-workflow, you must also install the ccg-workflow runtime. Initialize it with npx ccg-workflow.

That runtime provides the external dependencies these commands expect, including:

~/.claude/bin/codeagent-wrapper
~/.claude/.ccg/prompts/*

Without ccg-workflow, these multi-* commands will not run correctly.

Custom API endpoints, model gateways, and self-hosted models

ECC works through each harness's normal configuration, so you can use an official provider, a compatible custom API endpoint or model gateway, or a self-hosted model without changing ECC's workflows.

For Claude Code, ECC does not hardcode Anthropic-hosted transport settings. Minimal gateway example:

export ANTHROPIC_BASE_URL=https://your-gateway.example.com
export ANTHROPIC_AUTH_TOKEN=your-token
claude

If your gateway remaps model names, configure that in Claude Code rather than in ECC. ECC's hooks, skills, commands, and rules are model-provider agnostic once the claude CLI is already working. See Anthropic's LLM gateway documentation and model configuration documentation.

Run or self-host any open-source model behind that gateway using separate compute and serving setup. If you need GPU capacity, Itô is ECC's preferred compute sponsor; any GPU provider works. The sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving. Separately, ecc ito find invokes the explicitly configured canonical Itô CLI and submits a live authenticated RFQ; it does not reserve capacity. Managed inference through Itô is not live yet.

Self-host Kimi with ECC + Itô compute

The Kimi Code harness and the model-serving layer are separate. ECC configures the agent harness; you bring an API endpoint or self-host an open-weight Kimi model on your own GPU capacity. This adapter is verified against Kimi Code 0.31.x (@moonshot-ai/kimi-code):

1. Get GPU capacity
_{Use Itô or any GPU provider.}

2. Serve Kimi
_{Expose the chosen checkpoint through a compatible endpoint.}

3. Run Kimi Code with ECC
_{Install project instructions and skills, then start Kimi Code.}

Configure the endpoint with Kimi Code's official provider guide, then install ECC:

bash ./install.sh --target kimi --profile minimal
node scripts/ecc.js doctor --target kimi
kimi

Kimi Code discovers the installed .kimi-code/AGENTS.md instructions and .kimi-code/skills/ workflows natively; project-level .agents/skills/ is also an official discovery location. ECC safely merges project MCP entries into .kimi-code/mcp.json and does not change the user-level ~/.kimi-code/config.toml. Kimi Code supports native hooks, but ECC's current managed-project adapter does not configure them, so this installer does not offer Kimi hook profiles. The installer dry-run and regression suite verify that every managed Kimi write stays inside the project-local .kimi-code/ root.

Itô compute CLI bridge

ecc ito delegates to the separately installed canonical Itô client; ECC does not maintain a second API client. ecc ito login [--no-browser] performs device authorization, opens the Itô verification page by default, and persists a device token in macOS Keychain; --no-browser suppresses the page handoff. ECC itself does no browser automation. ecc ito auth is validation-only and rejects --no-browser. The available operations are ecc ito login, ecc ito auth, ecc ito find, ecc ito status, and the separately gated ecc ito evals. The matching MCP tools remain ito_auth, ito_find, and ito_status; ito_auth validates existing credentials and node qualification is CLI-only.

The ito-compute-cli package is currently unpublished. Build it locally from the Itô runtime repo (private while the desk hardens; design partners get access) under cli/ito-compute-cli, run npm ci and npm run check, then set ECC_ITO_CLI_EXECUTABLE to that build's absolute dist/bin/ito.js path. Login never inherits ITO_API_KEY; auth, find, and status forward ITO_API_KEY directly when configured, and ITO_AUTH_MODE=legacy is not required. ecc ito logout revokes the current device credential and retains its local copy if remote revocation cannot be confirmed. Device tokens use macOS Keychain by default; explicit file fallback must retain owner-only directory/file permissions. ECC does not discover this credential-bearing client through PATH. See the ito-compute skill for the full RFQ authority and MCP setup contract.

find submits a live authenticated RFQ. It does not reserve capacity. evals requires both ITO_ENABLE_SIXTYTWO_LIVE=1 and --live-sixtytwo, a separately installed sixtytwo-cli==0.3.33, an explicit node list, and an existing absolute configuration directory. It cannot rent, launch, recover, repair, or purchase. ECC exposes no quote lock, purchase, workload, or inference path, and it never replaces a missing client or failed live call with a local result.

Reset, repair, or uninstall

Reset / Uninstall ECC

If ECC feels duplicated, intrusive, or broken, inspect the managed state before reinstalling:

node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair
node scripts/ecc.js uninstall --dry-run

For direct uninstall:

node scripts/uninstall.js --dry-run
node scripts/uninstall.js

If you are leaving, the uninstall command prints an optional 20-second feedback form. It is a public GitHub issue, never blocks uninstall, and ECC does not upload diagnostics. You can also run ecc feedback at any time to see the problem, feedback, and feature routes.

Plugin users should remove the plugin from Claude Code, then delete only the rule folders they manually copied and no longer want. ECC only removes files recorded in its install-state. It does not claim unrelated files in your harness directories.

If you stacked methods, clean up in this order:

Remove the Claude Code plugin install.
Run the ECC uninstall command from the repo root to remove install-state-managed files.
Delete any extra rule folders you copied manually and no longer want.
Reinstall once, using a single path.

Coming soon: guided setup in release 2.2

Warning

These ECC package-runner commands are not available in the current npm release, 2.1.0. Do not run them until ecc-universal 2.2.0 is published.

The earlier README description—Recommended default: run the guided Claude plugin setup—was published too soon. That recommendation is withdrawn until release 2.2.

For Claude Code plugin setup, updates, scope changes, and hook-profile changes:

npx ecc-universal setup

Release 2.2 will support the same guided setup through modern package runners:

Package runner	Guided setup command
npm / npx	`npx ecc-universal setup`
pnpm	`pnpm dlx ecc-universal setup`
Yarn 2+	`yarn dlx ecc-universal setup`
Bun	`bunx ecc-universal setup`

Yarn Classic 1 does not provide yarn dlx; use npx, install the package globally, or upgrade Yarn for a temporary one-shot run after 2.2 is published.

The wizard inventories the official marketplace and every native Claude install scope before making changes, then installs, updates, or safely moves ecc@ecc to the scope you choose. Rerun the same command whenever you want to update ECC, change scope, or change its hook profile. This setup wizard currently configures the Claude Code plugin; use the multi-harness wizard below for Codex or Kimi Code.

To configure more than one coding agent in one reviewed flow, use the multi-harness wizard:

npx ecc-universal install --guided

It lets you select any combination of Claude Code, Codex, and Kimi Code, shows each install channel and destination, preflights every selection before the first write, and asks for one final confirmation.

Harness	Guided install behavior
Claude Code	Native `ecc@ecc` plugin with one `user`, `project`, or `local` scope and an ECC hook profile
Codex	Native Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned
Kimi Code	Managed project files under `./.kimi-code`; ECC hooks, model/provider settings, and authentication are not configured

For automation, make every provider-specific choice explicit:

npx ecc-universal install --guided \
  --harness claude --harness codex --harness kimi \
  --claude-scope local --claude-hooks standard \
  --profile core --yes

Verify the native guided Codex path and managed Kimi path without writing first:

npx ecc-universal install --guided --harness codex --dry-run
npx ecc-universal install --profile core --target kimi --dry-run

Additional package-name commands will also become available through the 2.2 alias:

npx ecc-universal consult "security reviews" --target claude
npx ecc-universal install --profile minimal --target claude --with capability:machine-learning
npx ecc-universal doctor --target kimi

Do not use npx ecc-install --profile minimal --target claude: ecc-install is a binary name inside ecc-universal, not a separately published npm package.

ECC also ships advanced managed adapters for cursor, antigravity, gemini, opencode, codebuddy, joycode, qwen, zed, hermes, and openclaw. Those targets still use their documented ecc install --target ... paths until each adapter has passed the guided collision, update, repair, and uninstall lifecycle matrix. Neither wizard silently installs into every detected harness.

Start Using ECC

Start with the workflow you need, not the full catalog.

What you are doing	Start here
Building a feature	`/ecc:plan "describe the feature"`, then `tdd-workflow`
Fixing a bug	Reproduce it with a failing test, then use `tdd-workflow`
Reviewing new code	`/code-review` for a fresh-context review
Repairing a build	`/build-fix`
Cleaning a codebase	`/refactor-clean`
Checking context pressure	`/context-budget`
Ending a long session	`/save-session` or `/learn-eval`
Resuming later	`/resume-session`
Auditing agent config	`/security-scan` or `npx -y ecc-agentshield scan --path .`

Plugin commands and manual commands

Claude Code plugin commands use the namespaced form:

/ecc:plan "Add authentication"

Manual installs may expose the shorter compatibility form:

/plan "Add authentication"

Skills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. Check what is installed with:

/plugin list ecc@ecc

Which agent should I use?

Skills are the canonical workflow surface; maintained slash entries stay available for command-first workflows.

I want to...	Use this surface	Agent used
Plan a new feature	`/ecc:plan "Add auth"`	planner
Design system architecture	`/ecc:plan` + architect agent	architect
Write code with tests first	`tdd-workflow` skill	tdd-guide
Review code I just wrote	`/code-review`	code-reviewer
Fix a failing build	`/build-fix`	build-error-resolver
Run end-to-end tests	`e2e-testing` skill	e2e-runner
Find security vulnerabilities	`/security-scan`	security-reviewer
Remove dead code	`/refactor-clean`	refactor-cleaner
Update documentation	`/update-docs`	doc-updater
Review Go code	`/go-review`	go-reviewer
Review Python code	`/python-review`	python-reviewer
Review F# code	(invoke `fsharp-reviewer` directly)	fsharp-reviewer
Review TypeScript/JavaScript code	(invoke `typescript-reviewer` directly)	typescript-reviewer
Develop HarmonyOS apps	(invoke `harmonyos-app-resolver` directly)	harmonyos-app-resolver
Audit database queries	(auto-delegated)	database-reviewer
Review production ML changes	`mle-workflow` skill + `mle-reviewer` agent	mle-reviewer

Common workflows

Slash forms below are shown where they remain part of the maintained command surface. Retired short-name shims such as /tdd and /eval live in legacy-command-shims/ for explicit opt-in only.

Starting a new feature:

/ecc:plan "Add user authentication with OAuth"
                                              -> planner creates implementation blueprint
tdd-workflow skill                            -> tdd-guide enforces write-tests-first
/code-review                                  -> code-reviewer checks your work

Fixing a bug:

tdd-workflow skill                            -> tdd-guide: write a failing test that reproduces it
                                              -> implement the fix, verify test passes
/code-review                                  -> code-reviewer: catch regressions

Preparing for production:

/security-scan                                -> security-reviewer: OWASP Top 10 audit
e2e-testing skill                             -> e2e-runner: critical user flow tests
/test-coverage                                -> verify 80%+ coverage

What's New: ECC 2.1

Important

NEW IN ECC 2.1: Plan Canvas · Kimi harness · self-hosted compute on Itô GPUs. See the full release notes →

Plan Canvas: review plans by pointing, not retyping

Your agent writes a plan, then opens it in a loopback-only browser canvas. Click the part you mean, attach numbered annotations, chat from a side rail, and hit Approve plan or Request changes. The verdict maps straight onto /plan's CONFIRM gate. Mermaid diagrams render live, and edits to the plan file reload the page.

It's harness- and model-agnostic: a plain CLI (ecc-plan-canvas) speaking JSON, so any agent can drive it. Try it: ask your agent to /ecc:plan anything, then review from the page instead of the terminal.

Open the plan used in this demo →

Also in 2.1

Kimi Code install target (--target kimi): ECC installs natively into Moonshot AI's Kimi Code CLI
Self-host on GPUs: a verified path with Itô, ECC's preferred compute sponsor, including the opt-in ecc ito find RFQ bridge (details and disclosures above in the install options)
Moonshot AI (Kimi), Itô, and Atlas Cloud are now public sponsors
Hermes + OpenClaw install targets, a Codex navigation guide, consolidated PostToolUse hooks, and supply-chain hardening

Current development: Unified Memory Vault

ecc memory gives Claude, Codex, Hermes, OpenClaw, Kimi, and other harnesses one local, inspectable Markdown format for durable context and handoffs. The optional ecc-memory-mcp stdio server exposes the same bounded save/search/read/doctor surface without enabling itself by default. Full detail in Share context between harnesses below.

Previous releases

Version	Highlights
v2.0.0	The Agent Harness Operating System: cross-harness graduation, control-pane substrate, `orch-*` orchestrators, Discord + ECC bot, single-connector MCP policy
v1.10.0	Surface refresh, operator workflows, ECC 2.0 alpha
v1.9.0	Selective install, ECC Tools Pro, 12 language ecosystems
v1.8.0	Harness performance and cross-platform reliability
v1.7.0	Cross-platform expansion and presentation builder
v1.6.0	Codex Edition and the ECC Tools GitHub App
v1.5.0	Universal Edition
v1.4.0	Multi-language rules, installation wizard, PM2 orchestration
v1.3.0	Complete OpenCode plugin support
v1.2.0	Unified commands and skills
v1.1.0	Cross-platform support and community fixes
v1.0.0	Official plugin release

Release history in detail

v2.0.0: The Agent Harness Operating System (Jun 2026)

Stable graduation of the 2.0 line: the control-pane substrate (session adapters + MCP inventory), the worktree-lifecycle service, the orch-* orchestrator family, and the launch of the ECC Discord community. Full notes: docs/releases/2.0.0/release-notes.md.

v2.0.0-rc.1: Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026)

Dashboard GUI: New Tkinter-based desktop application (ecc_dashboard.py or npm run dashboard) with dark/light theme toggle, font customization, and project logo in header and taskbar.
Public surface synced to the live repo: metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface.
Operator and outbound workflow expansion: brand-voice, social-graph-ranker, connections-optimizer, customer-billing-ops, ecc-tools-cost-audit, google-workspace-ops, project-flow-ops, and workspace-surface-audit round out the operator lane.
Media and launch tooling: manim-video, remotion-video-creation, and upgraded social publishing surfaces make technical explainers and launch content part of the same system.
Framework and product surface growth: nestjs-patterns, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond a single harness.
Itô prediction-market skill pack: ito-market-intelligence, ito-basket-compare, ito-trade-planner, ito-data-atlas-agent, prediction-market-oracle-research, and prediction-market-risk-review add public, non-advisory market/basket workflows while keeping live Itô API access gated and separate from ECC Tools billing.
Optimization skill pack: parallel-execution-optimizer, benchmark-optimization-loop, data-throughput-accelerator, latency-critical-systems, and recursive-decision-ledger turn repeated speed/recursion prompts into bounded benchmark, throughput, and decision-ledger workflows.
ECC 2.0 alpha in-tree: the Rust control-plane prototype in ecc2/ builds locally and exposes dashboard, start, sessions, status, stop, resume, and daemon commands.
Operator status snapshots: ecc status --markdown --write status.md turns the local state store into a portable handoff covering readiness, active sessions, skill-run health, install health, pending governance events, and linked work items from Linear/GitHub/handoffs.
Ecosystem hardening: AgentShield, ECC Tools cost controls, billing portal work, and website refreshes continue to ship around the core plugin instead of drifting into separate silos.

v1.9.0: Selective Install and Language Expansion (Mar 2026)

Selective install architecture: Manifest-driven install pipeline with install-plan.js and install-apply.js for targeted component installation. State store tracks what's installed and enables incremental updates.
6 new agents: typescript-reviewer, pytorch-build-resolver, java-build-resolver, java-reviewer, kotlin-reviewer, kotlin-build-resolver expand language coverage to 10 languages.
New skills: pytorch-patterns, documentation-lookup, bun-runtime, nextjs-turbopack, 8 operational domain skills, and mcp-server-patterns.
Session and state infrastructure: SQLite state store with query CLI, session adapters for structured recording, skill evolution foundation for self-improving skills.
Orchestration overhaul: Deterministic harness audit scoring, hardened orchestration status and launcher compatibility, observer loop prevention with 5-layer guard.
Observer reliability: Memory explosion fix with throttling and tail sampling, sandbox access fix, lazy-start logic, and re-entrancy guard.
12 language ecosystems: New rules for Java, PHP, Perl, Kotlin/Android/KMP, C++, and Rust join existing TypeScript, Python, Go, and common rules.
Community contributions: Korean and Chinese translations, biome hook optimization, video processing skills, operational skills, PowerShell installer, Antigravity IDE support.
CI hardening: 19 test failure fixes, catalog count enforcement, install manifest validation, and full test suite green.

v1.8.0: Harness Performance System (Mar 2026)

Harness-first release: ECC is explicitly framed as an agent harness performance system, not just a config pack.
Hook reliability overhaul: SessionStart root fallback, Stop-phase session summaries, and script-based hooks replacing fragile inline one-liners.
Hook runtime controls: ECC_HOOK_PROFILE=minimal|standard|strict and ECC_DISABLED_HOOKS=... for runtime gating without editing hook files.
New harness commands: /harness-audit, /loop-start, /loop-status, /quality-gate, /model-route.
NanoClaw v2: model routing, skill hot-load, session branch/search/export/compact/metrics.
Cross-harness parity: behavior tightened across Claude Code, Cursor, OpenCode, and Codex app/CLI.
997 internal tests passing: full suite green after hook/runtime refactor and compatibility updates.

v1.7.0: Cross-Platform Expansion and Presentation Builder (Feb 2026)

Codex app + CLI support: Direct AGENTS.md-based Codex support, installer targeting, and Codex docs
frontend-slides skill: Zero-dependency HTML presentation builder with PPTX conversion guidance and strict viewport-fit rules
5 new generic business/content skills: article-writing, content-engine, market-research, investor-materials, investor-outreach
Broader tool coverage: Cursor, Codex, and OpenCode support tightened so the same repo ships cleanly across all major harnesses
992 internal tests: Expanded validation and regression coverage across plugin, hooks, skills, and packaging

v1.6.0: Codex CLI, AgentShield, and Marketplace (Feb 2026)

Codex CLI support: New /codex-setup command generates codex.md for OpenAI Codex CLI compatibility
7 new skills: search-first, swift-actor-persistence, swift-protocol-di-testing, regex-vs-llm-structured-text, content-hash-cache-pattern, cost-aware-llm-pipeline, skill-stocktake
AgentShield integration: /security-scan runs AgentShield directly from Claude Code; 1282 tests, 102 rules
GitHub Marketplace: ECC Tools GitHub App live at github.com/marketplace/ecc-tools with free/pro/enterprise tiers
30+ community PRs merged: Contributions from 30 contributors across 6 languages
978 internal tests: Expanded validation suite across agents, skills, commands, hooks, and rules

v1.4.1: Bug Fix (Feb 2026)

Fixed instinct import content loss: parse_instinct_file() was silently dropping all content after frontmatter (Action, Evidence, Examples sections) during /instinct-import. (#148, #161)

v1.4.0: Multi-Language Rules, Installation Wizard, and PM2 (Feb 2026)

Interactive installation wizard: New configure-ecc skill provides guided setup with merge/overwrite detection
PM2 and multi-agent orchestration: 6 new commands (/pm2, /multi-plan, /multi-execute, /multi-backend, /multi-frontend, /multi-workflow) for managing complex multi-service workflows
Multi-language rules architecture: Rules restructured from flat files into common/ + typescript/ + python/ + golang/ directories. Install only the languages you need
Chinese (zh-CN) translations: Complete translation of all agents, commands, skills, and rules (80+ files)
GitHub Sponsors support: Sponsor the project via GitHub Sponsors
Enhanced CONTRIBUTING.md: Detailed PR templates for each contribution type

v1.3.0: OpenCode Plugin Support (Feb 2026)

Full OpenCode integration: 12 agents, 24 commands, 16 skills with hook support via OpenCode's plugin system (20+ event types)
3 native custom tools: run-tests, check-coverage, security-audit
LLM documentation: llms.txt for comprehensive OpenCode docs

v1.2.0: Unified Commands and Skills (Feb 2026)

Python/Django support: Django patterns, security, TDD, and verification skills
Java Spring Boot skills: Patterns, security, TDD, and verification for Spring Boot
Session management: /sessions command for session history
Continuous learning v2: Instinct-based learning with confidence scoring, import/export, evolution

See the full changelog in Releases.

Why Choose ECC?

Without a system	With ECC
Plans disappear into chat history	Plans become editable artifacts before implementation starts
"Please use TDD" is an instruction the model may forget	TDD becomes a gated RED -> GREEN -> REFACTOR workflow with evidence
The same context writes and reviews the code	A fresh-context reviewer looks for regressions and blind spots
Memory means saving an enormous transcript	Sessions are distilled into summaries, instincts, and reusable skills
Quality checks depend on reminders	Hooks can enforce deterministic checks outside the prompt
Agent configuration is trusted by default	AgentShield scans the harness itself as an attack surface

TDD: Test-Driven Development

/ecc:plan "Add usage-based billing alerts"
  -> confirm or edit the plan
  -> activate tdd-workflow
  -> capture RED evidence before implementation
  -> implement until GREEN
  -> review from fresh context
  -> fix findings with regression tests
  -> verify build, lint, types, and tests

A result is not just code. It's a trail of evidence: the plan, the failing test, the passing test, the review findings, and the final verification.

Skills keep the context focused

Rules, skills, agents, and hooks solve different problems. Keeping those jobs separate is how ECC adds capability without dumping the entire repository into every session.

Concept	What it does	Context behavior
Skills	Reusable workflows such as TDD, security review, or deep research	Loaded when the task needs them
Agents	Scoped workers with their own context and tool permissions	Isolate planning, implementation, and review
Rules	Durable project or language standards	Always loaded, so install them selectively
Hooks	Scripts triggered by harness events	Run outside the model context
Instincts	Patterns learned from real sessions with confidence scores	Recalled when relevant

Share context between harnesses

ECC's Memory Vault gives Claude, Codex, Hermes, OpenClaw, Kimi, and other harnesses one local, inspectable Markdown format for durable context and handoffs. Project and team memories live under .ecc/memory/; user memories live under ~/.ecc/memory/.

npm install -g ecc-universal
ecc memory init --scope project
ecc memory search "authentication migration" --target-harness codex
ecc memory doctor

Memory is unreviewed context, not executable policy. Verify important claims against authoritative sources and promote accepted knowledge into governed project documentation. The optional ecc-memory-mcp server exposes the same bounded save, search, read, and doctor surface without enabling itself by default.

Open the Unified Memory workflow →

Memory Vault in depth: scopes, handoffs, and trust boundaries

The Memory Vault stores portable ecc.memory.v1 Markdown documents instead of copying vendor transcripts or emailing context between agents. Project memories are protected by a fail-closed .gitignore; use the team scope only for human-inspected, version-controlled sharing. Team memories remain unreviewed context even after they are committed.

Skill-only, minimal, manual, and Claude plugin installs do not put the Memory Vault runtime on PATH. Install the npm runtime separately before using the CLI or optional MCP server:

npm install -g ecc-universal
ecc memory --help
command -v ecc-memory-mcp

# Initialize the project vault.
ecc memory init --scope project

# Write a handoff body to a regular file, then target the next harness.
ecc memory handoff \
  --from hermes \
  --target codex \
  --title "Continue authentication migration" \
  --body-file ./handoff.md

# Recall it from another harness.
ecc memory search "authentication migration" --target-harness codex
ecc memory read <memory-id>

# Validate the vault before sharing team memories.
ecc memory doctor

Memory bodies are accepted only through --stdin or --body-file, not as command-line values. The first release keeps every vault entry unreviewed and create-only; human review promotes accepted knowledge into governed project documentation rather than changing memory trust. Normal search recall returns active project and team memories. A direct ID read may inspect a non-active entry. User-scope recall must be requested explicitly. Agents must verify important claims against authoritative sources and must never treat recalled bodies as executable instructions or policy.

For opt-in MCP access, add the ecc-memory-vault entry from mcp-configs/mcp-servers.json to each harness that needs it, then run ecc-memory-mcp. The server exposes only memory_save, memory_search, memory_read, and memory_doctor. Each server must launch with a lowercase ECC_MEMORY_HARNESS identity; the identity is server-bound and cannot be supplied by a tool caller. User scope additionally requires the operator-controlled ECC_MEMORY_ALLOW_USER_SCOPE=1 opt-in. See skills/unified-memory/SKILL.md for the workflow and trust boundaries, and docs/design/ecc-memory-vault.md for the capability contract.

Guides

This repo is the raw code. The guides explain everything.

The Shorthand Guide
_{Setup, foundations, and day-one use. Read this first. (thread)}

The Longform Guide
_{Context economics, memory, evals, and parallel agents. (thread)}

The Security Guide
_{Prompt injection, hooks, MCP, and AgentShield. (thread)}

Topic	What You'll Learn
Token Optimization	Model selection, system prompt slimming, background processes
Memory Persistence	Hooks that save/load context across sessions automatically
Continuous Learning	Auto-extract patterns from sessions into reusable skills
Verification Loops	Checkpoint vs continuous evals, grader types, pass@k metrics
Parallelization	Git worktrees, cascade method, when to scale instances
Subagent Orchestration	The context problem, iterative retrieval pattern

Commands Quick Reference | Manual Adaptation Guide

What's Inside

ECC/
|-- agents/           # 68 specialized subagents for delegation
|-- skills/           # 287 reusable workflows loaded on demand
|-- commands/         # 94 maintained slash-command shims
|-- rules/            # opt-in common and language standards
|-- hooks/            # runtime automation and enforcement
|-- scripts/          # install, repair, sync, orchestration, and checks
|-- .claude-plugin/   # Claude Code marketplace manifest
|-- .codex/           # Codex reference configuration and agent roles
|-- .opencode/        # OpenCode plugin, commands, and instructions
|-- .cursor/          # Cursor rules and hook adapter
|-- docs/             # public setup, architecture, and operating guides

The root is the source of truth. Platform adapters package or map these same workflows instead of maintaining separate copies.

Annotated component catalog

ECC/
|-- .claude-plugin/   # Plugin and marketplace manifests
|   |-- plugin.json         # Plugin metadata and component paths
|   |-- marketplace.json    # Marketplace catalog for /plugin marketplace add
|
|-- agents/           # 67 specialized subagents for delegation
|   |-- planner.md           # Feature implementation planning
|   |-- architect.md         # System design decisions
|   |-- tdd-guide.md         # Test-driven development
|   |-- code-reviewer.md     # Quality and security review
|   |-- security-reviewer.md # Vulnerability analysis
|   |-- build-error-resolver.md
|   |-- e2e-runner.md        # Playwright E2E testing
|   |-- refactor-cleaner.md  # Dead code cleanup
|   |-- doc-updater.md       # Documentation sync
|   |-- docs-lookup.md       # Documentation/API lookup
|   |-- chief-of-staff.md    # Communication triage and drafts
|   |-- loop-operator.md     # Autonomous loop execution
|   |-- harness-optimizer.md # Harness config tuning
|   |-- cpp-reviewer.md      # C++ code review
|   |-- cpp-build-resolver.md # C++ build error resolution
|   |-- fsharp-reviewer.md   # F# functional code review
|   |-- go-reviewer.md       # Go code review
|   |-- go-build-resolver.md # Go build error resolution
|   |-- python-reviewer.md   # Python code review
|   |-- database-reviewer.md # Database/Supabase review
|   |-- typescript-reviewer.md # TypeScript/JavaScript code review
|   |-- java-reviewer.md     # Java/Spring Boot code review
|   |-- java-build-resolver.md # Java/Maven/Gradle build errors
|   |-- kotlin-reviewer.md   # Kotlin/Android/KMP code review
|   |-- kotlin-build-resolver.md # Kotlin/Gradle build errors
|   |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development
|   |-- rust-reviewer.md     # Rust code review
|   |-- rust-build-resolver.md # Rust build error resolution
|   |-- pytorch-build-resolver.md # PyTorch/CUDA training errors
|   |-- mle-reviewer.md      # Production ML pipeline, eval, serving, and monitoring review
|
|-- skills/           # Workflow definitions and domain knowledge
|   |-- coding-standards/           # Language best practices
|   |-- clickhouse-io/              # ClickHouse analytics, queries, data engineering
|   |-- backend-patterns/           # API, database, caching patterns
|   |-- frontend-patterns/          # React, Next.js patterns
|   |-- frontend-slides/            # HTML slide decks and PPTX-to-web presentation workflows
|   |-- article-writing/            # Long-form writing in a supplied voice without generic AI tone
|   |-- content-engine/             # Multi-platform social content and repurposing workflows
|   |-- market-research/            # Source-attributed market, competitor, and investor research
|   |-- investor-materials/         # Pitch decks, one-pagers, memos, and financial models
|   |-- investor-outreach/          # Personalized fundraising outreach and follow-up
|   |-- continuous-learning/        # Legacy v1 Stop-hook pattern extraction
|   |-- continuous-learning-v2/     # Instinct-based learning with confidence scoring
|   |-- iterative-retrieval/        # Progressive context refinement for subagents
|   |-- strategic-compact/          # Manual compaction suggestions (Longform Guide)
|   |-- tdd-workflow/               # TDD methodology
|   |-- security-review/            # Security checklist
|   |-- eval-harness/               # Verification loop evaluation (Longform Guide)
|   |-- verification-loop/          # Continuous verification (Longform Guide)
|   |-- videodb/                    # Video and audio: ingest, search, edit, generate, stream
|   |-- golang-patterns/            # Go idioms and best practices
|   |-- golang-testing/             # Go testing patterns, TDD, benchmarks
|   |-- cpp-coding-standards/       # C++ coding standards from C++ Core Guidelines
|   |-- cpp-testing/                # C++ testing with GoogleTest, CMake/CTest
|   |-- django-patterns/            # Django patterns, models, views
|   |-- django-security/            # Django security best practices
|   |-- django-tdd/                 # Django TDD workflow
|   |-- django-verification/        # Django verification loops
|   |-- laravel-patterns/           # Laravel architecture patterns
|   |-- laravel-security/           # Laravel security best practices
|   |-- laravel-tdd/                # Laravel TDD workflow
|   |-- laravel-verification/       # Laravel verification loops
|   |-- python-patterns/            # Python idioms and best practices
|   |-- python-testing/             # Python testing with pytest
|   |-- quarkus-patterns/           # Java Quarkus patterns
|   |-- quarkus-security/           # Quarkus security
|   |-- quarkus-tdd/                # Quarkus TDD
|   |-- quarkus-verification/       # Quarkus verification
|   |-- springboot-patterns/        # Java Spring Boot patterns
|   |-- springboot-security/        # Spring Boot security
|   |-- springboot-tdd/             # Spring Boot TDD
|   |-- springboot-verification/    # Spring Boot verification
|   |-- configure-ecc/              # Interactive installation wizard
|   |-- security-scan/              # AgentShield security auditor integration
|   |-- java-coding-standards/      # Java coding standards
|   |-- jpa-patterns/               # JPA/Hibernate patterns
|   |-- postgres-patterns/          # PostgreSQL optimization patterns
|   |-- nutrient-document-processing/ # Document processing with Nutrient API
|   |-- database-migrations/        # Migration patterns (Prisma, Drizzle, Django, Go)
|   |-- api-design/                 # REST API design, pagination, error responses
|   |-- deployment-patterns/        # CI/CD, Docker, health checks, rollbacks
|   |-- docker-patterns/            # Docker Compose, networking, volumes, container security
|   |-- e2e-testing/                # Playwright E2E patterns and Page Object Model
|   |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing
|   |-- cost-aware-llm-pipeline/    # LLM cost optimization, model routing, budget tracking
|   |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing
|   |-- swift-actor-persistence/    # Thread-safe Swift data persistence with actors
|   |-- swift-protocol-di-testing/  # Protocol-based DI for testable Swift code
|   |-- search-first/               # Research-before-coding workflow
|   |-- skill-stocktake/            # Audit skills and commands for quality
|   |-- liquid-glass-design/        # iOS 26 Liquid Glass design system
|   |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels
|   |-- swift-concurrency-6-2/      # Swift 6.2 Approachable Concurrency
|   |-- mle-workflow/               # Production ML data contracts, evals, deployment, monitoring
|   |-- perl-patterns/              # Modern Perl 5.36+ idioms and best practices
|   |-- perl-security/              # Perl security patterns, taint mode, safe I/O
|   |-- perl-testing/               # Perl TDD with Test2::V0, prove, Devel::Cover
|   |-- autonomous-loops/           # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration
|   |-- plankton-code-quality/      # Write-time code quality enforcement with Plankton hooks
|   |-- codehealth-mcp/             # Optional CodeScene Code Health MCP skill (opt-in)
|   |-- docs/examples/project-guidelines-template.md  # Template for project-specific skills
|
|-- commands/         # Maintained slash-entry compatibility; prefer skills/
|   |-- plan.md             # /plan - Implementation planning
|   |-- code-review.md      # /code-review - Quality review
|   |-- build-fix.md        # /build-fix - Fix build errors
|   |-- refactor-clean.md   # /refactor-clean - Dead code removal
|   |-- quality-gate.md     # /quality-gate - Verification gate
|   |-- learn.md            # /learn - Extract patterns mid-session (Longform Guide)
|   |-- learn-eval.md       # /learn-eval - Extract, evaluate, and save patterns
|   |-- checkpoint.md       # /checkpoint - Save verification state (Longform Guide)
|   |-- setup-pm.md         # /setup-pm - Configure package manager
|   |-- go-review.md        # /go-review - Go code review
|   |-- go-test.md          # /go-test - Go TDD workflow
|   |-- go-build.md         # /go-build - Fix Go build errors
|   |-- skill-create.md     # /skill-create - Generate skills from git history
|   |-- instinct-status.md  # /instinct-status - View learned instincts
|   |-- instinct-import.md  # /instinct-import - Import instincts
|   |-- instinct-export.md  # /instinct-export - Export instincts
|   |-- evolve.md           # /evolve - Cluster instincts into skills
|   |-- prune.md            # /prune - Delete expired pending instincts
|   |-- pm2.md              # /pm2 - PM2 service lifecycle management
|   |-- multi-plan.md       # /multi-plan - Multi-agent task decomposition
|   |-- multi-execute.md    # /multi-execute - Orchestrated multi-agent workflows
|   |-- multi-backend.md    # /multi-backend - Backend multi-service orchestration
|   |-- multi-frontend.md   # /multi-frontend - Frontend multi-service orchestration
|   |-- multi-workflow.md   # /multi-workflow - General multi-service workflows
|   |-- sessions.md         # /sessions - Session history management
|   |-- test-coverage.md    # /test-coverage - Test coverage analysis
|   |-- update-docs.md      # /update-docs - Update documentation
|   |-- update-codemaps.md  # /update-codemaps - Update codemaps
|   |-- python-review.md    # /python-review - Python code review
|-- legacy-command-shims/   # Opt-in archive for retired shims such as /tdd and /eval
|   |-- tdd.md              # /tdd - Prefer the tdd-workflow skill
|   |-- e2e.md              # /e2e - Prefer the e2e-testing skill
|   |-- eval.md             # /eval - Prefer the eval-harness skill
|   |-- verify.md           # /verify - Prefer the verification-loop skill
|   |-- orchestrate.md      # /orchestrate - Prefer dmux-workflows or multi-workflow
|
|-- rules/            # Always-follow guidelines (copy to ~/.claude/rules/ecc/)
|   |-- README.md            # Structure overview and installation guide
|   |-- common/              # Language-agnostic principles
|   |   |-- coding-style.md    # Immutability, file organization
|   |   |-- git-workflow.md    # Commit format, PR process
|   |   |-- testing.md         # TDD, 80% coverage requirement
|   |   |-- performance.md     # Model selection, context management
|   |   |-- patterns.md        # Design patterns, skeleton projects
|   |   |-- hooks.md           # Hook architecture, TodoWrite
|   |   |-- agents.md          # When to delegate to subagents
|   |   |-- security.md        # Mandatory security checks
|   |-- typescript/          # TypeScript/JavaScript specific
|   |-- python/              # Python specific
|   |-- golang/              # Go specific
|   |-- swift/               # Swift specific
|   |-- php/                 # PHP specific
|   |-- arkts/               # HarmonyOS / ArkTS specific
|
|-- hooks/            # Trigger-based automations
|   |-- README.md                 # Hook documentation, recipes, and customization guide
|   |-- hooks.json                # All hooks config (PreToolUse, PostToolUse, Stop, etc.)
|   |-- memory-persistence/       # Session lifecycle hooks (Longform Guide)
|   |-- strategic-compact/        # Compaction suggestions (Longform Guide)
|
|-- scripts/          # Cross-platform Node.js scripts
|   |-- lib/                     # Shared utilities
|   |   |-- utils.js             # Cross-platform file/path/system utilities
|   |   |-- package-manager.js   # Package manager detection and selection
|   |-- hooks/                   # Hook implementations
|   |   |-- session-start.js     # Load context on session start
|   |   |-- session-end.js       # Save state on session end
|   |   |-- pre-compact.js       # Pre-compaction state saving
|   |   |-- suggest-compact.js   # Strategic compaction suggestions
|   |   |-- evaluate-session.js  # Extract patterns from sessions
|   |-- setup-package-manager.js # Interactive PM setup
|
|-- tests/            # Test suite
|   |-- lib/                     # Library tests
|   |-- hooks/                   # Hook tests
|   |-- run-all.js               # Run all tests
|
|-- contexts/         # Dynamic system prompt injection contexts (Longform Guide)
|   |-- dev.md              # Development mode context
|   |-- review.md           # Code review mode context
|   |-- research.md         # Research/exploration mode context
|
|-- examples/         # Example configurations and sessions
|   |-- CLAUDE.md             # Example project-level config
|   |-- user-CLAUDE.md        # Example user-level config
|   |-- saas-nextjs-CLAUDE.md   # Real-world SaaS (Next.js + Supabase + Stripe)
|   |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)
|   |-- django-api-CLAUDE.md      # Real-world Django REST API (DRF + Celery)
|   |-- laravel-api-CLAUDE.md     # Real-world Laravel API (PostgreSQL + Redis)
|   |-- rust-api-CLAUDE.md        # Real-world Rust API (Axum + SQLx + PostgreSQL)
|
|-- mcp-configs/      # MCP server configurations
|   |-- mcp-servers.json    # GitHub, Supabase, Vercel, Railway, etc.
|
|-- ecc_dashboard.py  # Desktop GUI dashboard (Tkinter)
|
|-- marketplace.json  # Self-hosted marketplace config (for /plugin marketplace add)

Dashboard GUI

Launch the desktop dashboard to visually explore ECC components:

npm run dashboard
# or
python3 ./ecc_dashboard.py

Features:

Tabbed interface: Agents, Skills, Commands, Rules, Settings
Dark/Light theme toggle
Font customization (family and size)
Project logo in header and taskbar
Search and filter across all components

Ecosystem Tools

Skill Creator: generate skills from your git history

Two ways to generate skills from your repository:

Option A: Local Analysis (Built-in)

Use the /skill-create command for local analysis without external services:

/skill-create                    # Analyze current repo
/skill-create --instincts        # Also generate instincts for continuous-learning-v2

This analyzes your git history locally and generates SKILL.md files.

Option B: GitHub App (Advanced)

For advanced features (10k+ commits, auto-PRs, team sharing):

Install ECC Tools GitHub App | ecc.tools

# Comment on any issue:
/ecc-tools analyze

Both options create:

SKILL.md files: Ready-to-use skills for the active harness
Instinct collections: For continuous-learning-v2
Pattern extraction: Learns from your commit history

AgentShield: security auditor for agent configs

Built at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 tests, 98% coverage, 102 static analysis rules.

Scan your agent configuration for vulnerabilities, misconfigurations, and injection risks.

# Quick scan (no install needed)
npx ecc-agentshield scan

# Auto-fix safe issues
npx ecc-agentshield scan --fix

# Deep analysis with three Opus 4.6 agents
npx ecc-agentshield scan --opus --stream

# Generate secure config from scratch
npx ecc-agentshield init

What it scans: CLAUDE.md, settings.json, MCP configs, hooks, agent definitions, and skills across 5 categories: secrets detection (14 patterns), permission auditing, hook injection analysis, MCP server risk profiling, and agent config review.

The --opus flag runs three Claude Opus 4.6 agents in a red-team/blue-team/auditor pipeline. The attacker finds exploit chains, the defender evaluates protections, and the auditor synthesizes both into a prioritized risk assessment. Adversarial reasoning, not just pattern matching.

Output formats: Terminal (color-graded A-F), JSON (CI pipelines), Markdown, HTML. Exit code 2 on critical findings for build gates.

Use /security-scan in Claude Code to run it, or add to CI with the GitHub Action.

GitHub | npm

Continuous Learning v2: instincts

The instinct-based learning system automatically learns your patterns:

/instinct-status        # Show learned instincts with confidence
/instinct-import <file> # Import instincts from others
/instinct-export        # Export your instincts for sharing
/evolve                 # Cluster related instincts into skills

See skills/continuous-learning-v2/ for full documentation. Keep continuous-learning/ only when you explicitly want the legacy v1 Stop-hook learned-skill flow.

Key Concepts

Agents, skills, hooks, and rules explained

Agents

Subagents handle delegated tasks with limited scope. Example:

---
name: code-reviewer
description: Reviews code for quality, security, and maintainability
tools: Read, Grep, Glob, Bash
model: opus
---

You are a senior code reviewer...

Skills

Skills are the primary workflow surface. They can be invoked directly, suggested automatically, and reused by agents. ECC still ships maintained commands/ during migration, while retired short-name shims live under legacy-command-shims/ for explicit opt-in only. New workflow development should land in skills/ first.

# TDD Workflow

1. Define interfaces first
2. Write failing tests (RED)
3. Implement minimal code (GREEN)
4. Refactor (IMPROVE)
5. Verify 80%+ coverage

Hooks

Hooks fire on tool events. Example: warn about console.log:

{
  "matcher": "tool == \"Edit\" && tool_input.file_path matches \"\\\\.(ts|tsx|js|jsx)$\"",
  "hooks": [{
    "type": "command",
    "command": "#!/bin/bash\ngrep -n 'console\\.log' \"$file_path\" && echo '[Hook] Remove console.log' >&2"
  }]
}

Rules

Rules are always-follow guidelines, organized into common/ (language-agnostic) + language-specific directories:

rules/
  common/          # Universal principles (always install)
  typescript/      # TS/JS specific patterns and tools
  python/          # Python specific patterns and tools
  golang/          # Go specific patterns and tools
  swift/           # Swift specific patterns and tools
  php/             # PHP specific patterns and tools
  arkts/           # HarmonyOS / ArkTS patterns and constraints

See rules/README.md for installation and structure details.

Cross-Platform Support

ECC's core Node.js CLI and managed installers run on Windows, macOS, and Linux, but optional capabilities are not at full parity. Some continuous-learning, GAN, and orchestration paths still require Bash or Python; harnesses also expose different hook, agent, and skill APIs.

Platform	Status	Current limitation
Linux	Supported core	Optional features may require Bash, Python, or provider-specific tools.
macOS	Supported core	The standalone GAN shell path is not compatible with the system Bash 3.2 and currently has a score-parsing defect (#2674).
Windows + WSL	Supported core	WSL follows the Linux paths; Windows host integrations still vary by harness.
Windows native	Supported with limitations	Continuous-learning v2's observer daemon and memory-vault writes have open native-Windows defects (#2489, #2626). Shell-backed optional features require Git Bash/WSL or are unavailable.

Treat stable, beta, experimental, and instruction-only below as capability statements, not marketing tiers.

Package manager detection

The plugin automatically detects your preferred package manager (npm, pnpm, yarn, or bun) with the following priority:

Environment variable: CLAUDE_PACKAGE_MANAGER
Project config: .claude/package-manager.json
package.json: packageManager field
Lock file: Detection from package-lock.json, yarn.lock, pnpm-lock.yaml, or bun.lockb
Global config: ~/.claude/package-manager.json
Fallback: First available package manager

To set your preferred package manager:

# Via environment variable
export CLAUDE_PACKAGE_MANAGER=pnpm

# Via global config
node scripts/setup-package-manager.js --global pnpm

# Via project config
node scripts/setup-package-manager.js --project bun

# Detect current setting
node scripts/setup-package-manager.js --detect

Or use the /setup-pm command.

Hook runtime controls (env vars)

Use runtime flags to tune strictness or disable specific hooks temporarily:

# Hook strictness profile (default: standard)
export ECC_HOOK_PROFILE=standard

# Comma-separated hook IDs to disable
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

# Cap SessionStart additional context (default: 8000 chars)
export ECC_SESSION_START_MAX_CHARS=4000

# Disable SessionStart additional context entirely for low-context/local-model setups
export ECC_SESSION_START_CONTEXT=off

# Session-tmp retention window in days (default: 30).
# Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning).
export ECC_SESSION_RETENTION_DAYS=14

# Cap how many learned instincts SessionStart injects into context (default: 6)
export ECC_MAX_INJECTED_INSTINCTS=6

# Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7)
export ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7

# SessionStart ranks injected instincts by confidence + project/stack relevance
# (default: on). Project-scoped instincts, and instincts whose domain/trigger
# matches the detected stack (languages, frameworks, plus terraform/dbt markers),
# get a small ranking boost so they surface above unrelated higher-confidence
# ones. Set to off/false/0/no to rank by confidence alone.
export ECC_INSTINCT_RELEVANCE_RANKING=on

# Keep context/scope/loop warnings but suppress API-rate cost estimates
export ECC_CONTEXT_MONITOR_COST_WARNINGS=off

Windows PowerShell:

[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')
[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')

Agent data home (multi-harness isolation)

Memory persistence hooks (session summaries, learned skills, session aliases, metrics) store data under a single agent data root. By default that root is ~/.claude. When you use ECC in both Claude Code and Cursor on the same machine, set a separate root for Cursor so the two environments do not overwrite each other's session files:

# Cursor-only boundary (Claude Code keeps the default ~/.claude)
export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"

Paths resolved under that root include:

$ECC_AGENT_DATA_HOME/session-data/: session summaries
$ECC_AGENT_DATA_HOME/skills/learned/: learned skills from evaluate-session
$ECC_AGENT_DATA_HOME/session-aliases.json: session aliases
$ECC_AGENT_DATA_HOME/metrics/: cost and activity metrics

See affaan-m/ECC#2065.

Platform Support

Harness	Status	Recommended distribution	Important limitation
Claude Code	Stable primary	Plugin or selective installer	The plugin advertises the installed catalog to the model; use a selective/manual profile when context footprint matters. Optional shell-backed skills are not portable to every OS.
Codex	Supported sync; marketplace experimental	Repo config or `sync-ecc-to-codex.sh`	No ECC hook runtime. The marketplace package can omit shared repository content from Codex's cache; use sync for the reliable path.
Cursor	Beta project adapter	Selective installer into `.cursor/`	Agent discovery varies by Cursor build, and ECC's installer paths do not yet expose identical hook sets (#2419).
OpenCode	Beta built plugin	Build plugin, then selective installer	ECC ships a subset of the catalog and the reference config pins Anthropic models; select models available to your provider (#2617).
GitHub Copilot	Instruction-only	Checked-in instructions and prompt files	No ECC hooks, runtime agents, delegation, or native skill discovery.
Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode	Experimental/minimal adapters	Harness-specific selective target	File placement and instruction portability are tested; full Claude feature parity is not claimed.

Cross-tool capability map

Capability	Claude Code	Codex	Cursor	OpenCode	GitHub Copilot
Instructions	Native	Native `AGENTS.md`	Project rules	Plugin instructions	Native instruction file
Skills	Native installed set	Native synced set	Build-dependent/project set	Built subset	Prompt/instruction references only
Agents/delegation	Native agents	Codex multi-agent roles	Build-dependent project agents	Plugin agents	Not supported
ECC hooks	Native plugin hooks	Not supported	Cursor hook adapter; install-path differences remain	Plugin events	Not supported
MCP configuration	Available, explicit activation	TOML merge through sync	Explicit project/user config	Provider/plugin config	Not supplied by ECC
Parity with Claude Code	Primary reference	Partial	Partial	Partial	Not a parity target

Key architectural decisions:

AGENTS.md at root is the universal cross-tool file (read by Claude Code, Cursor, Codex, and OpenCode; GitHub Copilot uses .github/copilot-instructions.md instead)
DRY adapter pattern lets Cursor reuse Claude Code's hook scripts without duplication
Skills format (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
Codex's lack of hooks is compensated by AGENTS.md, optional model_instructions_file overrides, and sandbox permissions

Cursor IDE support in depth

ECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout.

# macOS/Linux
./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php

# Windows PowerShell
.\install.ps1 --target cursor typescript
.\install.ps1 --target cursor python golang swift php

What's included for Cursor

Component	Count	Details
Hook Events	15	sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more
Hook Scripts	16	Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter
Rules	34	9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP)
Agents	48	`.cursor/agents/ecc-*.md` when installed; prefixed to avoid collisions with user or marketplace agents
Skills	Shared + Bundled	`.cursor/skills/` for translated additions
Commands	Shared	`.cursor/commands/` if installed
MCP Config	Shared	`.cursor/mcp.json` if installed

Cursor loading notes

ECC does not install root AGENTS.md into .cursor/. Cursor treats nested AGENTS.md files as directory context, so copying ECC's repo identity into a host project would pollute that project.

Cursor-native loading behavior can vary by Cursor build. ECC installs agents as .cursor/agents/ecc-*.md; if your Cursor build does not expose project agents, those files still work as explicit reference definitions instead of hidden global prompt context.

Memory and data isolation (Cursor + Claude Code)

ECC memory hooks reuse the same scripts/hooks/*.js as Claude Code. For Cursor, ECC tries to keep memory out of ~/.claude automatically:

Cursor sessionStart hook (installed to .cursor/hooks.json on --target cursor) injects ECC_AGENT_DATA_HOME for the whole composer session.
Hook runtime default: when CURSOR_VERSION or CURSOR_PROJECT_DIR is present, hooks default to ~/.cursor/ecc if the env var is unset.
Project config: .cursor/ecc-agent-data.json documents and overrides the path (agentDataHome).
Always-on rule: .cursor/rules/ecc-agent-data-home.mdc reminds the agent where memory lives.

You can still override explicitly:

export ECC_AGENT_DATA_HOME="$HOME/.cursor/ecc"

To share memory with Claude Code on purpose, set ECC_AGENT_DATA_HOME=~/.claude in the shell or in .cursor/ecc-agent-data.json.

Continuous learning v2 instincts remain separate under CLV2_HOMUNCULUS_DIR (default ~/.local/share/ecc-homunculus).

Hook architecture (DRY adapter pattern)

Cursor has more hook events than Claude Code (20 vs 8). The .cursor/hooks/adapter.js module transforms Cursor's stdin JSON to Claude Code's format, allowing existing scripts/hooks/*.js to be reused without duplication.

Cursor stdin JSON -> adapter.js -> transforms -> scripts/hooks/*.js
                                                (shared with Claude Code)

Key hooks:

beforeShellExecution: Blocks dev servers outside tmux (exit 2), git push review
afterFileEdit: Auto-format + TypeScript check + console.log warning
beforeSubmitPrompt: Detects secrets (sk-, ghp_, AKIA patterns) in prompts
beforeTabFileRead: Blocks Tab from reading .env, .key, .pem files (exit 2)
beforeMCPExecution / afterMCPExecution: MCP audit logging

Rules format

Cursor rules use YAML frontmatter with description, globs, and alwaysApply:

---
description: "TypeScript coding style extending common rules"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---

Codex macOS app + CLI support in depth

ECC provides a supported Codex repo/sync path for the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills. The ECC marketplace route remains experimental. For repo navigation, surface ownership, and PR diff packet guidance, start with docs/CODEX-NAVIGATION-GUIDE.md.

# Run Codex CLI in the repo: AGENTS.md and .codex/ are auto-detected
codex

# Automatic setup: sync ECC assets (AGENTS.md, skills, MCP servers) into ~/.codex
npm install && bash scripts/sync-ecc-to-codex.sh

# Or manually: copy the reference config to your home directory
cp .codex/config.toml ~/.codex/config.toml

The sync script safely merges ECC MCP servers into your existing ~/.codex/config.toml using an add-only strategy: it never removes or modifies your existing servers. Run with --dry-run to preview changes, or --update-mcp to force-refresh ECC servers to the latest recommended config.

For Context7, ECC uses the canonical Codex section name [mcp_servers.context7] while still launching the @upstash/context7-mcp package. If you already have a legacy [mcp_servers.context7-mcp] entry, --update-mcp migrates it to the canonical section name.

Codex macOS app:

Open this repository as your workspace.
The root AGENTS.md is auto-detected.
.codex/config.toml and .codex/agents/*.toml work best when kept project-local.
The reference .codex/config.toml intentionally does not pin model or model_provider, so Codex uses its own current default unless you override it.
Optional: copy .codex/config.toml to ~/.codex/config.toml for global defaults; keep the multi-agent role files project-local unless you also copy .codex/agents/.

What's included for Codex

Component	Count	Details
Config	1	`.codex/config.toml`: top-level approvals/sandbox/web_search, MCP servers, notifications, profiles
AGENTS.md	2	Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement)
Skills	32	`.agents/skills/`: SKILL.md + agents/openai.yaml per skill
MCP Servers	6	GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking (7 with Supabase via `--update-mcp` sync)
Profiles	2	`strict` (read-only sandbox) and `yolo` (full auto-approve)
Agent Roles	3	`.codex/agents/`: explorer, reviewer, docs-researcher

Skills at .agents/skills/ are auto-loaded by Codex. Canonical Anthropic skills such as claude-api, frontend-design, and skill-creator are intentionally not re-bundled here. Install those from anthropics/skills when you want the official versions.

Key limitation

Codex does not yet provide Claude-style hook execution parity. ECC enforcement there is instruction-based via AGENTS.md, optional model_instructions_file overrides, and sandbox/approval settings.

Multi-agent support

Current Codex builds support stable multi-agent workflows.

Enable features.multi_agent = true in .codex/config.toml
Define roles under [agents.<name>]
Point each role at a file under .codex/agents/
Use /agent in the CLI to inspect or steer child agents

ECC ships three sample role configs:

Role	Purpose
`explorer`	Read-only codebase evidence gathering before edits
`reviewer`	Correctness, security, and missing-test review
`docs_researcher`	Documentation and API verification before release/docs changes

Zed support

ECC provides Zed project support through a conservative .zed adapter for project-local settings, flattened rules, agents, commands, and skills.

./install.sh --profile minimal --target zed

.\install.ps1 --profile minimal --target zed

The adapter writes ECC-managed files under .zed/ and keeps BYOK/OpenRouter credentials out of the repo. Configure Zed account or API keys through Zed's own settings UI or your local user settings.

OpenCode support in depth

ECC provides a beta OpenCode plugin integration with instructions, a catalog subset, commands, custom tools, and hook events. It does not provide feature parity with Claude Code, and the reference model IDs must exist in the user's configured provider.

# Install OpenCode
npm install -g opencode

# Run in the repository root
opencode

The configuration is automatically detected from .opencode/opencode.json.

Hook support via plugins

OpenCode's plugin system has 20+ event types:

Claude Code Hook	OpenCode Plugin Event
PreToolUse	`tool.execute.before`
PostToolUse	`tool.execute.after`
Stop	`session.idle`
SessionStart	`session.created`
SessionEnd	`session.deleted`

Additional OpenCode events: file.edited, file.watcher.updated, message.updated, lsp.client.diagnostics, tui.toast.show, and more.

Plugin installation

Option 1: Use directly

cd ECC
opencode

Option 2: Install as npm package

npm install ecc-universal

Then add to your opencode.json:

{
  "plugin": ["ecc-universal"]
}

That npm plugin entry enables ECC's published OpenCode plugin module (hooks/events and plugin tools). It does not automatically add ECC's full command/agent/instruction catalog to your project config.

For the full ECC OpenCode setup, either:

run OpenCode inside this repository, or
copy the bundled .opencode/ config assets into your project and wire the instructions, agent, and command entries in opencode.json

Documentation

Migration Guide: .opencode/MIGRATION.md
OpenCode Plugin README: .opencode/README.md
Consolidated Rules: .opencode/instructions/INSTRUCTIONS.md
LLM Documentation: llms.txt (complete OpenCode docs for LLMs)

GitHub Copilot support in depth

ECC provides GitHub Copilot support for VS Code via Copilot Chat's native instruction and prompt file system. No extra tooling required.

What's included for GitHub Copilot

Component	File	Purpose
Core instructions	`.github/copilot-instructions.md`	Always-loaded rules: coding style, security, testing, git workflow
VS Code settings	`.vscode/settings.json`	Per-task instruction files for code gen, test gen, and commit messages
Plan prompt	`.github/prompts/plan.prompt.md`	Phased implementation planning
TDD prompt	`.github/prompts/tdd.prompt.md`	Red-Green-Improve cycle
Security review prompt	`.github/prompts/security-review.prompt.md`	Deep OWASP-aligned security analysis
Build fix prompt	`.github/prompts/build-fix.prompt.md`	Systematic build and CI error resolution
Refactor prompt	`.github/prompts/refactor.prompt.md`	Dead code cleanup and simplification

The files are already in place: open any repo that contains this project and GitHub Copilot Chat will automatically pick up .github/copilot-instructions.md. The committed .vscode/settings.json enables chat.promptFiles so VS Code can load the reusable prompts from .github/prompts/.

To use the workflow prompts in Copilot Chat:

Open the Copilot Chat panel in VS Code.
Click the paperclip / attach icon and select Prompt..., or type / and choose a prompt.
Select the prompt (e.g. plan, tdd, security-review).

Feature coverage

ECC Feature	Copilot equivalent
Coding standards	Always-on via `copilot-instructions.md`
Security checklist	Always-on + `security-review` prompt
Testing / TDD	Always-on + `tdd` prompt
Implementation planning	`plan` prompt
Code review	External PR review via CodeRabbit + Greptile
Build error resolution	`build-fix` prompt
Refactoring	`refactor` prompt
Commit message format	Per-task instruction in `settings.json`
Hooks / automation	Not supported (Copilot has no hook system)
Agents / delegation	Not supported (Copilot has no subagent API)

Limitations

GitHub Copilot does not have a hook system or a subagent API, so ECC's hook automations (auto-format, TypeScript check, session persistence, dev-server guard) and agent delegation are unavailable. The instruction and prompt layer still brings the full ECC coding philosophy (standards, security, TDD, and workflow) into every Copilot Chat session.

What changed in v2.0.0

ECC v2.0.0 stabilizes the 2.0 line with the public Hermes operator story, 281 skills, 67 agents, 94 command shims, session adapters, MCP inventory, worktree lifecycle services, orchestrator workflows, and the ECC Discord community.

Token Optimization

Agent usage can be expensive if you don't manage token consumption. These settings significantly reduce costs without sacrificing quality. Full guide: docs/token-optimization.md.

Recommended settings

Add to ~/.claude/settings.json:

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

Setting	Default	Recommended	Impact
`model`	opus	sonnet	~60% cost reduction; handles 80%+ of coding tasks
`MAX_THINKING_TOKENS`	31,999	10,000	~70% reduction in hidden thinking cost per request
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	95	50	Compacts earlier, better quality in long sessions
`ECC_CONTEXT_MONITOR_COST_WARNINGS`	on	off for subscription users	Suppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings

Switch to Opus only when you need deep architectural reasoning:

/model opus

Daily workflow commands

Command	When to Use
`/model sonnet`	Default for most tasks
`/model opus`	Complex architecture, debugging, deep reasoning
`/clear`	Between unrelated tasks (free, instant reset)
`/compact`	At logical task breakpoints (research done, milestone complete)
`/cost`	Monitor token spending during session

If you use a subscription and the context monitor's API-rate estimates are not useful, set ECC_CONTEXT_MONITOR_COST_WARNINGS=off. This only suppresses the agent-facing cost warnings; it does not disable context exhaustion, scope, or loop warnings.

Strategic compaction

The strategic-compact skill suggests /compact at logical breakpoints instead of relying on auto-compaction at 95% context. See skills/strategic-compact/SKILL.md for the full decision guide.

When to compact:

After research/exploration, before implementation
After completing a milestone, before starting the next
After debugging, before continuing feature work
After a failed approach, before trying a new one

When NOT to compact:

Mid-implementation (you'll lose variable names, file paths, partial state)

Context window management

Critical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.

Keep under 10 MCPs enabled per project
Keep under 80 tools active
Use /mcp to disable unused Claude Code MCP servers; those runtime choices persist in ~/.claude.json
Use ECC_DISABLED_MCPS only to filter ECC-generated MCP configs during install/sync flows
If context is getting heavy, run /context-budget and remove rules you do not need

Agent teams cost warning: Agent Teams spawns multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews). For simple sequential tasks, subagents are more token-efficient.

Requirements

Claude Code CLI version + hooks auto-loading behavior

Claude Code CLI version

Minimum version: v2.1.0 or later. The plugin requires Claude Code CLI v2.1.0+ due to changes in how the plugin system handles hooks.

Check your version:

claude --version

Important: hooks auto-loading behavior

WARNING: For Contributors: Do NOT add a "hooks" field to .claude-plugin/plugin.json. This is enforced by a regression test.

Claude Code v2.1+ automatically loads hooks/hooks.json from any installed plugin by convention. Explicitly declaring it in plugin.json causes a duplicate detection error:

Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file

History: This has caused repeated fix/revert cycles in this repo (#29, #52, #103). The behavior changed between Claude Code versions, leading to confusion. There is now a regression test to prevent this from being reintroduced.

Security

Install ECC only from official sources:

GitHub repository: https://github.com/affaan-m/ECC
Claude Code plugin: ecc@ecc
npm packages: ecc-universal and ecc-agentshield
GitHub App: https://github.com/apps/ecc-tools
Website: https://ecc.tools

Scan a project with AgentShield:

npx -y ecc-agentshield scan --path .

Report a vulnerability. Use the private process in SECURITY.md (GitHub private vulnerability reporting). Please do not open public issues for security reports.
Built-in guardrails. GateGuard gates destructive shell commands (including rm, force/path git checkout, and destructive find -exec) before they run; the supply-chain IOC scanner runs in CI; and AgentShield audits your own agent, hook, MCP, permission, and secret surfaces (/security-scan).

Hooks, MCP servers, and context controls

Hooks can run shell commands, MCP servers can hold credentials, and project instructions can enter an agent's context. Treat all three as executable configuration.

Do not copy raw hooks/hooks.json into ~/.claude/settings.json after a plugin install. Modern Claude Code versions load plugin hooks automatically, and a second copy can make them fire twice.

Use /mcp for Claude Code runtime disables; Claude Code persists those choices in ~/.claude.json.

ECC_DISABLED_MCPS is an ECC install/sync filter, not a live Claude Code toggle.

If context is getting heavy, run /context-budget, remove rules you do not need, and disable unused MCP servers. See the token optimization guide.

Security references:

Troubleshooting

ECC appears twice or hooks fire twice

The usual cause is installing the Claude plugin and then running ./install.sh --profile full on top of it.

Remove the Claude Code plugin install.
Run node scripts/ecc.js uninstall --dry-run from the ECC checkout.
Remove extra rule folders you manually copied and no longer want.
Reinstall once, using one path.

For hook-specific checks, see the hooks README.

My hooks aren't working / "Duplicate hooks file" errors

Do NOT add a "hooks" field to .claude-plugin/plugin.json. Claude Code v2.1+ automatically loads hooks/hooks.json from installed plugins. Explicitly declaring it causes duplicate detection errors. See #29, #52, #103.

Codex marketplace installs but skills do not load

Run the cache check from an ECC checkout:

node scripts/codex/check-plugin-cache.js

If it reports unresolved parent references, use bash scripts/sync-ecc-to-codex.sh. Registration in codex plugin list confirms the marketplace entry, not that every referenced file reached the plugin cache. Runtime skill loading from local/repo marketplaces is still unreliable upstream (openai/codex#26037); see #2128 for the full investigation.

My context window is shrinking

Too many MCP servers eat your context. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k. SessionStart context is capped at 8000 characters by default; lower it with ECC_SESSION_START_MAX_CHARS=4000 or disable it with ECC_SESSION_START_CONTEXT=off for local-model or low-context setups.

Fix: Disable unused MCPs from Claude Code with /mcp. Claude Code writes those runtime choices to ~/.claude.json; .claude/settings.json and .claude/settings.local.json are not reliable toggles for already-loaded MCP servers.

Keep under 10 MCPs enabled and under 80 tools active.

Can I use only some components (e.g., just agents)?

Yes. Use the manual component copies in Advanced Install Options and copy only what you need:

# Just agents
cp agents/*.md ~/.claude/agents/

# Just rules
mkdir -p ~/.claude/rules/ecc/
cp -r rules/common ~/.claude/rules/ecc/

Each component is fully independent.

Does this work with Cursor / OpenCode / Codex / Antigravity / GitHub Copilot?

Yes. ECC is cross-platform:

Cursor: Pre-translated configs in .cursor/. See Platform Support.
Gemini CLI: Experimental project-local support via .gemini/GEMINI.md and shared installer plumbing.
OpenCode: Beta plugin integration in .opencode/; provider model selection and catalog parity remain limited.
Codex: Supported repo/sync path for macOS app and CLI; ECC's marketplace package remains experimental.
GitHub Copilot (VS Code): Instruction and prompt layer via .github/copilot-instructions.md, .vscode/settings.json, and .github/prompts/.
Antigravity: Tightly integrated setup for workflows, skills, and flattened rules in .agent/. See Antigravity Guide.
JoyCode / CodeBuddy: Project-local selective install adapters for commands, agents, skills, and flattened rules. See JoyCode Adapter Guide.
Qwen CLI: Home-directory selective install adapter for commands, agents, skills, rules, and Qwen config. See Qwen CLI Adapter Guide.
Zed: Project-local selective install adapter for .zed/settings.json, flattened rules, commands, agents, and skills.
Non-native harnesses: Manual fallback path for chat-style interfaces. See Manual Adaptation Guide.
Claude Code: Native. This is the primary target.

My platform is not listed

Use the manual adaptation guide, or open a GitHub discussion with the harness name and the file, skill, command, and hook formats it supports.

Running Tests

The plugin includes a comprehensive test suite:

# Run all tests
node tests/run-all.js

# Run individual test files
node tests/lib/utils.test.js
node tests/lib/package-manager.test.js
node tests/hooks/hooks.test.js

Background

I've been using Claude Code since the experimental rollout. Won the Anthropic x Forum Ventures hackathon in Sep 2025 with @DRodriguezFX, built zenith.chat entirely with agentic workflows.

These configs are battle-tested across multiple production applications.

Community and Project

Sponsors and ECC Pro

ECC stays free because sponsors and Pro users fund the work. Sponsor logos are at the top of this README; the full roster and tiers are in SPONSORS.md.

ECC Pro adds private-repo analysis, PR-triggered audits, AgentShield-backed scanning, automatic push and PR checks, pooled team usage, and priority support through the hosted GitHub App.

ECC Pro
_{Hosted GitHub App for private repos}

Sponsor ECC
_{Fund the OSS work}

Community
_{Q&A, ideas, and Show and Tell}

GitHub App
_{PR audits and hosted workflows}

Become a sponsor | Sponsor tiers | Sponsorship program

Contributing

Contributions are welcome across skills, agents, rules, hooks, docs, tests, adapters, and security improvements.

The short version:

Fork the repo
Create your skill in skills/your-skill-name/SKILL.md (with YAML frontmatter)
Or create an agent in agents/your-agent.md
Submit a PR with a clear description of what it does and when to use it

Ideas for contributions:

Language-specific skills (Rust, C#, Kotlin, Java): Go, Python, Perl, Swift, TypeScript, and HarmonyOS/ArkTS already included
Framework-specific configs (Rails, FastAPI): Django, NestJS, Spring Boot, and Laravel already included
DevOps agents (Kubernetes, Terraform, AWS, Docker)
Testing strategies (different frameworks, visual regression)
Domain-specific knowledge (ML, data engineering, mobile)

License

MIT. Use it freely, adapt it to your workflow, and contribute back when you can.

Star this repo if it helps. Read the guides. Build something great.

GitHub JavaScript Daily Trending Repositories

addyosmani/agent-skills

Agent Skills

Commands

Quick Start

Adoption

All 24 Skills

Meta - Discover which skill applies

Define - Clarify what to build

Plan - Break it down

Build - Write the code

Verify - Prove it works

Review - Quality gates before merge

Ship - Deploy with confidence

Agent Personas

Reference Checklists

How Skills Work

Project Structure

Why Agent Skills?

How it compares

Contributing

Team

License

chr0nzz/traefik-manager

Traefik Manager

Highlights

Quick Start

Screenshots

Features

Routes

Middlewares

Live Dashboard & Monitoring

Static Config Editor (optional - mount traefik.yml read-write)

Backups

Multi-Server (Agents)

Notifications

Security

Deployment

Documentation

Mobile App

Tech Stack

Contributing

Contributors

License

santifer/career-ops

What Is This

The CareerOps Manifesto

Features

Quick Start

Global install

Antigravity CLI Integration

Native Antigravity CLI

Codex Integration

Interactive Codex

One-shot Codex (codex exec)

Grok Build CLI Integration

Native Grok Build CLI

Standalone Gemini API Script (No CLI install needed)

Usage

How It Works

Pre-configured Portals

Dashboard TUI

Project Structure

Tech Stack

Also Open Source

FAQ

About the Author

Disclaimer

Contributors

License & Trademark

Let's Connect

techjarves/Uncensored-Local-Studio

Uncensored AI Studio

📖 Table of Contents

📖 What is Uncensored AI Studio?

🌟 Key Features

⚙️ Workspace & Engine Architecture

Supported Models

Image generation

Text, speech, and TTS

Static Config Editor (optional - mount `traefik.yml` read-write)

One-shot Codex (`codex exec`)