GitHub All Languages Monthly Trending

NousResearch/hermes-agent

The agent that grows with you

Hermes Agent ☤

The self-improving AI agent built by Nous Research. It's the only agent with a built-in learning loop — it creates skills from experience, improves them during use, nudges itself to persist knowledge, searches its own past conversations, and builds a deepening model of who you are across sessions. Run it on a $5 VPS, a GPU cluster, or serverless infrastructure that costs nearly nothing when idle. It's not tied to your laptop — talk to it from Telegram while it works on a cloud VM.

Use any model you want — Nous Portal, OpenRouter (200+ models), NVIDIA NIM (Nemotron), Xiaomi MiMo, z.ai/GLM, Kimi/Moonshot, MiniMax, Hugging Face, OpenAI, or your own endpoint. Switch with hermes model — no code changes, no lock-in.

A real terminal interface	Full TUI with multiline editing, slash-command autocomplete, conversation history, interrupt-and-redirect, and streaming tool output.
Lives where you do	Telegram, Discord, Slack, WhatsApp, Signal, and CLI — all from a single gateway process. Voice memo transcription, cross-platform conversation continuity.
A closed learning loop	Agent-curated memory with periodic nudges. Autonomous skill creation after complex tasks. Skills self-improve during use. FTS5 session search with LLM summarization for cross-session recall. Honcho dialectic user modeling. Compatible with the agentskills.io open standard.
Scheduled automations	Built-in cron scheduler with delivery to any platform. Daily reports, nightly backups, weekly audits — all in natural language, running unattended.
Delegates and parallelizes	Spawn isolated subagents for parallel workstreams. Write Python scripts that call tools via RPC, collapsing multi-step pipelines into zero-context-cost turns.
Runs anywhere, not just your laptop	Six terminal backends — local, Docker, SSH, Daytona, Singularity, and Modal. Daytona and Modal offer serverless persistence — your agent's environment hibernates when idle and wakes on demand, costing nearly nothing between sessions. Run it on a $5 VPS or a GPU cluster.
Research-ready	Batch trajectory generation, Atropos RL environments, trajectory compression for training the next generation of tool-calling models.

Quick Install

curl -fsSL https://raw.githubusercontent.com/NousResearch/hermes-agent/main/scripts/install.sh | bash

Works on Linux, macOS, WSL2, and Android via Termux. The installer handles the platform-specific setup for you.

Android / Termux: The tested manual path is documented in the Termux guide. On Termux, Hermes installs a curated .[termux] extra because the full .[all] extra currently pulls Android-incompatible voice dependencies.

Windows: Native Windows is not supported. Please install WSL2 and run the command above.

After installation:

source ~/.bashrc    # reload shell (or: source ~/.zshrc)
hermes              # start chatting!

Getting Started

hermes              # Interactive CLI — start a conversation
hermes model        # Choose your LLM provider and model
hermes tools        # Configure which tools are enabled
hermes config set   # Set individual config values
hermes gateway      # Start the messaging gateway (Telegram, Discord, etc.)
hermes setup        # Run the full setup wizard (configures everything at once)
hermes claw migrate # Migrate from OpenClaw (if coming from OpenClaw)
hermes update       # Update to the latest version
hermes doctor       # Diagnose any issues

📖 Full documentation →

CLI vs Messaging Quick Reference

Hermes has two entry points: start the terminal UI with hermes, or run the gateway and talk to it from Telegram, Discord, Slack, WhatsApp, Signal, or Email. Once you're in a conversation, many slash commands are shared across both interfaces.

Action	CLI	Messaging platforms
Start chatting	`hermes`	Run `hermes gateway setup` + `hermes gateway start`, then send the bot a message
Start fresh conversation	`/new` or `/reset`	`/new` or `/reset`
Change model	`/model [provider:model]`	`/model [provider:model]`
Set a personality	`/personality [name]`	`/personality [name]`
Retry or undo the last turn	`/retry`, `/undo`	`/retry`, `/undo`
Compress context / check usage	`/compress`, `/usage`, `/insights [--days N]`	`/compress`, `/usage`, `/insights [days]`
Browse skills	`/skills` or `/<skill-name>`	`/skills` or `/<skill-name>`
Interrupt current work	`Ctrl+C` or send a new message	`/stop` or send a new message
Platform-specific status	`/platforms`	`/status`, `/sethome`

For the full command lists, see the CLI guide and the Messaging Gateway guide.

Documentation

All documentation lives at hermes-agent.nousresearch.com/docs:

Section	What's Covered
Quickstart	Install → setup → first conversation in 2 minutes
CLI Usage	Commands, keybindings, personalities, sessions
Configuration	Config file, providers, models, all options
Messaging Gateway	Telegram, Discord, Slack, WhatsApp, Signal, Home Assistant
Security	Command approval, DM pairing, container isolation
Tools & Toolsets	40+ tools, toolset system, terminal backends
Skills System	Procedural memory, Skills Hub, creating skills
Memory	Persistent memory, user profiles, best practices
MCP Integration	Connect any MCP server for extended capabilities
Cron Scheduling	Scheduled tasks with platform delivery
Context Files	Project context that shapes every conversation
Architecture	Project structure, agent loop, key classes
Contributing	Development setup, PR process, code style
CLI Reference	All commands and flags
Environment Variables	Complete env var reference

Migrating from OpenClaw

If you're coming from OpenClaw, Hermes can automatically import your settings, memories, skills, and API keys.

During first-time setup: The setup wizard (hermes setup) automatically detects ~/.openclaw and offers to migrate before configuration begins.

Anytime after install:

hermes claw migrate              # Interactive migration (full preset)
hermes claw migrate --dry-run    # Preview what would be migrated
hermes claw migrate --preset user-data   # Migrate without secrets
hermes claw migrate --overwrite  # Overwrite existing conflicts

What gets imported:

SOUL.md — persona file
Memories — MEMORY.md and USER.md entries
Skills — user-created skills → ~/.hermes/skills/openclaw-imports/
Command allowlist — approval patterns
Messaging settings — platform configs, allowed users, working directory
API keys — allowlisted secrets (Telegram, OpenRouter, OpenAI, Anthropic, ElevenLabs)
TTS assets — workspace audio files
Workspace instructions — AGENTS.md (with --workspace-target)

See hermes claw migrate --help for all options, or use the openclaw-migration skill for an interactive agent-guided migration with dry-run previews.

Contributing

We welcome contributions! See the Contributing Guide for development setup, code style, and PR process.

Quick start for contributors — clone and go with setup-hermes.sh:

git clone https://github.com/NousResearch/hermes-agent.git
cd hermes-agent
./setup-hermes.sh     # installs uv, creates venv, installs .[all], symlinks ~/.local/bin/hermes
./hermes              # auto-detects the venv, no need to `source` first

Manual path (equivalent to the above):

curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv venv --python 3.11
source venv/bin/activate
uv pip install -e ".[all,dev]"
python -m pytest tests/ -q

RL Training (optional): To work on the RL/Tinker-Atropos integration:
git submodule update --init tinker-atropos
uv pip install -e "./tinker-atropos"

Community

💬 Discord
📚 Skills Hub
🐛 Issues
💡 Discussions
🔌 HermesClaw — Community WeChat bridge: Run Hermes Agent and OpenClaw on the same WeChat account.

License

MIT — see LICENSE.

Built by Nous Research.

forrestchang/andrej-karpathy-skills

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

Karpathy-Inspired Claude Code Guidelines

Check out my new project Multica — an open-source platform for running and managing coding agents with reusable skills.

Follow me on X: https://x.com/jiayuan_jy

A single CLAUDE.md file to improve Claude Code behavior, derived from Andrej Karpathy's observations on LLM coding pitfalls.

The Problems

From Andrej's post:

"The models make wrong assumptions on your behalf and just run along with them without checking. They don't manage their confusion, don't seek clarifications, don't surface inconsistencies, don't present tradeoffs, don't push back when they should."

"They really like to overcomplicate code and APIs, bloat abstractions, don't clean up dead code... implement a bloated construction over 1000 lines when 100 would do."

"They still sometimes change/remove comments and code they don't sufficiently understand as side effects, even if orthogonal to the task."

The Solution

Four principles in one file that directly address these issues:

Principle	Addresses
Think Before Coding	Wrong assumptions, hidden confusion, missing tradeoffs
Simplicity First	Overcomplication, bloated abstractions
Surgical Changes	Orthogonal edits, touching code you shouldn't
Goal-Driven Execution	Leverage through tests-first, verifiable success criteria

The Four Principles in Detail

1. Think Before Coding

Don't assume. Don't hide confusion. Surface tradeoffs.

LLMs often pick an interpretation silently and run with it. This principle forces explicit reasoning:

State assumptions explicitly — If uncertain, ask rather than guess
Present multiple interpretations — Don't pick silently when ambiguity exists
Push back when warranted — If a simpler approach exists, say so
Stop when confused — Name what's unclear and ask for clarification

2. Simplicity First

Minimum code that solves the problem. Nothing speculative.

Combat the tendency toward overengineering:

No features beyond what was asked
No abstractions for single-use code
No "flexibility" or "configurability" that wasn't requested
No error handling for impossible scenarios
If 200 lines could be 50, rewrite it

The test: Would a senior engineer say this is overcomplicated? If yes, simplify.

3. Surgical Changes

Touch only what you must. Clean up only your own mess.

When editing existing code:

Don't "improve" adjacent code, comments, or formatting
Don't refactor things that aren't broken
Match existing style, even if you'd do it differently
If you notice unrelated dead code, mention it — don't delete it

When your changes create orphans:

Remove imports/variables/functions that YOUR changes made unused
Don't remove pre-existing dead code unless asked

The test: Every changed line should trace directly to the user's request.

4. Goal-Driven Execution

Define success criteria. Loop until verified.

Transform imperative tasks into verifiable goals:

Instead of...	Transform to...
"Add validation"	"Write tests for invalid inputs, then make them pass"
"Fix the bug"	"Write a test that reproduces it, then make it pass"
"Refactor X"	"Ensure tests pass before and after"

For multi-step tasks, state a brief plan:

1. [Step] → verify: [check]
2. [Step] → verify: [check]
3. [Step] → verify: [check]

Strong success criteria let the LLM loop independently. Weak criteria ("make it work") require constant clarification.

Install

Option A: Claude Code Plugin (recommended)

From within Claude Code, first add the marketplace:

/plugin marketplace add forrestchang/andrej-karpathy-skills

Then install the plugin:

/plugin install andrej-karpathy-skills@karpathy-skills

This installs the guidelines as a Claude Code plugin, making the skill available across all your projects.

Option B: CLAUDE.md (per-project)

New project:

curl -o CLAUDE.md https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md

Existing project (append):

echo "" >> CLAUDE.md
curl https://raw.githubusercontent.com/forrestchang/andrej-karpathy-skills/main/CLAUDE.md >> CLAUDE.md

Key Insight

From Andrej:

"LLMs are exceptionally good at looping until they meet specific goals... Don't tell it what to do, give it success criteria and watch it go."

The "Goal-Driven Execution" principle captures this: transform imperative instructions into declarative goals with verification loops.

How to Know It's Working

These guidelines are working if you see:

Fewer unnecessary changes in diffs — Only requested changes appear
Fewer rewrites due to overcomplication — Code is simple the first time
Clarifying questions come before implementation — Not after mistakes
Clean, minimal PRs — No drive-by refactoring or "improvements"

Customization

These guidelines are designed to be merged with project-specific instructions. Add them to your existing CLAUDE.md or create a new one.

For project-specific rules, add sections like:

## Project-Specific Guidelines

- Use TypeScript strict mode
- All API endpoints must have tests
- Follow the existing error handling patterns in `src/utils/errors.ts`

Tradeoff Note

These guidelines bias toward caution over speed. For trivial tasks (simple typo fixes, obvious one-liners), use judgment — not every change needs the full rigor.

The goal is reducing costly mistakes on non-trivial work, not slowing down simple tasks.

License

MIT

Crosstalk-Solutions/project-nomad

Project N.O.M.A.D, is a self-contained, offline survival computer packed with critical tools, knowledge, and AI to keep you informed and empowered—anytime, anywhere.

Project N.O.M.A.D.

Node for Offline Media, Archives, and Data

Knowledge That Never Goes Offline

Project N.O.M.A.D. is a self-contained, offline-first knowledge and education server packed with critical tools, knowledge, and AI to keep you informed and empowered—anytime, anywhere.

Installation & Quickstart

Project N.O.M.A.D. can be installed on any Debian-based operating system (we recommend Ubuntu). Installation is completely terminal-based, and all tools and resources are designed to be accessed through the browser, so there's no need for a desktop environment if you'd rather setup N.O.M.A.D. as a "server" and access it through other clients.

Note: sudo/root privileges are required to run the install script

Quick Install (Debian-based OS Only)

sudo apt-get update && \
sudo apt-get install -y curl && \
curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/install_nomad.sh \
  -o install_nomad.sh && \
sudo bash install_nomad.sh

Project N.O.M.A.D. is now installed on your device! Open a browser and navigate to http://localhost:8080 (or http://DEVICE_IP:8080) to start exploring!

For a complete step-by-step walkthrough (including Ubuntu installation), see the Installation Guide.

Advanced Installation

For more control over the installation process, copy and paste the Docker Compose template into a docker-compose.yml file and customize it to your liking (be sure to replace any placeholders with your actual values). Then, run docker compose up -d to start the Command Center and its dependencies. Note: this method is recommended for advanced users only, as it requires familiarity with Docker and manual configuration before starting.

How It Works

N.O.M.A.D. is a management UI ("Command Center") and API that orchestrates a collection of containerized tools and resources via Docker. It handles installation, configuration, and updates for everything — so you don't have to.

Built-in capabilities include:

AI Chat with Knowledge Base — local AI chat powered by Ollama or you can use OpenAI API compatible software such as LM Studio or llama.cpp, with document upload and semantic search (RAG via Qdrant)
Information Library — offline Wikipedia, medical references, ebooks, and more via Kiwix
Education Platform — Khan Academy courses with progress tracking via Kolibri
Offline Maps — downloadable regional maps via ProtoMaps
Data Tools — encryption, encoding, and analysis via CyberChef
Notes — local note-taking via FlatNotes
System Benchmark — hardware scoring with a community leaderboard
Easy Setup Wizard — guided first-time configuration with curated content collections

N.O.M.A.D. also includes built-in tools like a Wikipedia content selector, ZIM library manager, and content explorer.

What's Included

Capability	Powered By	What You Get
Information Library	Kiwix	Offline Wikipedia, medical references, survival guides, ebooks
AI Assistant	Ollama + Qdrant	Built-in chat with document upload and semantic search
Education Platform	Kolibri	Khan Academy courses, progress tracking, multi-user support
Offline Maps	ProtoMaps	Downloadable regional maps with search and navigation
Data Tools	CyberChef	Encryption, encoding, hashing, and data analysis
Notes	FlatNotes	Local note-taking with markdown support
System Benchmark	Built-in	Hardware scoring, Builder Tags, and community leaderboard

Device Requirements

While many similar offline survival computers are designed to be run on bare-minimum, lightweight hardware, Project N.O.M.A.D. is quite the opposite. To install and run the available AI tools, we highly encourage the use of a beefy, GPU-backed device to make the most of your install.

At it's core, however, N.O.M.A.D. is still very lightweight. For a barebones installation of the management application itself, the following minimal specs are required:

Note: Project N.O.M.A.D. is not sponsored by any hardware manufacturer and is designed to be as hardware-agnostic as possible. The harware listed below is for example/comparison use only

Minimum Specs

Processor: 2 GHz dual-core processor or better
RAM: 4GB system memory
Storage: At least 5 GB free disk space
OS: Debian-based (Ubuntu recommended)
Stable internet connection (required during install only)

To run LLM's and other included AI tools:

Optimal Specs

Processor: AMD Ryzen 7 or Intel Core i7 or better
RAM: 32 GB system memory
Graphics: NVIDIA RTX 3060 or AMD equivalent or better (more VRAM = run larger models)
Storage: At least 250 GB free disk space (preferably on SSD)
OS: Debian-based (Ubuntu recommended)
Stable internet connection (required during install only)

For detailed build recommendations at three price points ($150–$1,000+), see the Hardware Guide.

Again, Project N.O.M.A.D. itself is quite lightweight - it's the tools and resources you choose to install with N.O.M.A.D. that will determine the specs required for your unique deployment

Running AI models on a different host

By default, N.O.M.A.D.'s installer will attempt to setup Ollama on the host when the AI Assistant is installed. However, if you would like to run the AI model on a different host, you can go to the settings of of the AI assistant and input a URL for either an ollama or OpenAI-compatible API server (such as LM Studio).
Note that if you use Ollama on a different host, you must start the server with this option OLLAMA_HOST=0.0.0.0.
Ollama is the preferred way to use the AI assistant as it has features such as model download that OpenAI API does not support. So when using LM Studio for example, you will have to use LM Studio to download models. You are responsible for the setup of Ollama/OpenAI server on the other host.

Frequently Asked Questions (FAQ)

For answers to common questions about Project N.O.M.A.D., please see our FAQ page.

About Internet Usage & Privacy

Project N.O.M.A.D. is designed for offline usage. An internet connection is only required during the initial installation (to download dependencies) and if you (the user) decide to download additional tools and resources at a later time. Otherwise, N.O.M.A.D. does not require an internet connection and has ZERO built-in telemetry.

To test internet connectivity, N.O.M.A.D. attempts to make a request to Cloudflare's utility endpoint, https://1.1.1.1/cdn-cgi/trace and checks for a successful response.

About Security

By design, Project N.O.M.A.D. is intended to be open and available without hurdles - it includes no authentication. If you decide to connect your device to a local network after install (e.g. for allowing other devices to access it's resources), you can block/open ports to control which services are exposed.

Will authentication be added in the future? Maybe. It's not currently a priority, but if there's enough demand for it, we may consider building in an optional authentication layer in a future release to support uses cases where multiple users need access to the same instance but with different permission levels (e.g. family use with parental controls, classroom use with teacher/admin accounts, etc.). We have a suggestion for this on our public roadmap, so if this is something you'd like to see, please upvote it here: https://roadmap.projectnomad.us/posts/1/user-authentication-please-build-in-user-auth-with-admin-user-roles

For now, we recommend using network-level controls to manage access if you're planning to expose your N.O.M.A.D. instance to other devices on a local network. N.O.M.A.D. is not designed to be exposed directly to the internet, and we strongly advise against doing so unless you really know what you're doing, have taken appropriate security measures, and understand the risks involved.

Contributing

Contributions are welcome and appreciated! Please see CONTRIBUTING.md for guidelines on how to contribute to the project.

Community & Resources

Website: www.projectnomad.us - Learn more about the project
Discord: Join the Community - Get help, share your builds, and connect with other NOMAD users
Benchmark Leaderboard: benchmark.projectnomad.us - See how your hardware stacks up against other NOMAD builds
Troubleshooting Guide: TROUBLESHOOTING.md - Find solutions to common issues
FAQ: FAQ.md - Find answers to frequently asked questions

License

Project N.O.M.A.D. is licensed under the Apache License 2.0.

Helper Scripts

Once installed, Project N.O.M.A.D. has a few helper scripts should you ever need to troubleshoot issues or perform maintenance that can't be done through the Command Center. All of these scripts are found in Project N.O.M.A.D.'s install directory, /opt/project-nomad

Start Script - Starts all installed project containers

sudo bash /opt/project-nomad/start_nomad.sh

Stop Script - Stops all installed project containers

sudo bash /opt/project-nomad/stop_nomad.sh

Update Script - Attempts to pull the latest images for the Command Center and its dependencies (i.e. mysql) and recreate the containers. Note: this only updates the Command Center containers. It does not update the installable application containers - that should be done through the Command Center UI

sudo bash /opt/project-nomad/update_nomad.sh

Uninstall Script - Need to start fresh? Use the uninstall script to make your life easy. Note: this cannot be undone!

curl -fsSL https://raw.githubusercontent.com/Crosstalk-Solutions/project-nomad/refs/heads/main/install/uninstall_nomad.sh -o uninstall_nomad.sh && sudo bash uninstall_nomad.sh

bytedance/deer-flow

An open-source long-horizon SuperAgent harness that researches, codes, and creates. With the help of sandboxes, memories, tools, skill, subagents and message gateway, it handles different levels of tasks that could take minutes to hours.

🦌 DeerFlow - 2.0

English | 中文 | 日本語 | Français | Русский

On February 28th, 2026, DeerFlow claimed the 🏆 #1 spot on GitHub Trending following the launch of version 2. Thanks a million to our incredible community — you made this happen! 💪🔥

DeerFlow (Deep Exploration and Efficient Research Flow) is an open-source super agent harness that orchestrates sub-agents, memory, and sandboxes to do almost anything — powered by extensible skills.

https://github.com/user-attachments/assets/a8bcadc4-e040-4cf2-8fda-dd768b999c18

Note

DeerFlow 2.0 is a ground-up rewrite. It shares no code with v1. If you're looking for the original Deep Research framework, it's maintained on the 1.x branch — contributions there are still welcome. Active development has moved to 2.0.

Official Website

Learn more and see real demos on our official website.

Coding Plan from ByteDance Volcengine

We strongly recommend using Doubao-Seed-2.0-Code, DeepSeek v3.2 and Kimi 2.5 to run DeerFlow
Learn more
中国大陆地区的开发者请点击这里

InfoQuest

DeerFlow has newly integrated the intelligent search and crawling toolset independently developed by BytePlus--InfoQuest (supports free online experience)

🦌 DeerFlow - 2.0

One-Line Agent Setup

If you use Claude Code, Codex, Cursor, Windsurf, or another coding agent, you can hand it the setup instructions in one sentence:

Help me clone DeerFlow if needed, then bootstrap it for local development by following https://raw.githubusercontent.com/bytedance/deer-flow/main/Install.md

That prompt is intended for coding agents. It tells the agent to clone the repo if needed, choose Docker when available, and stop with the exact next command plus any missing config the user still needs to provide.

Quick Start

Configuration

Clone the DeerFlow repository

git clone https://github.com/bytedance/deer-flow.git
cd deer-flow

Run the setup wizard

From the project root directory (deer-flow/), run:
```
make setup
```
This launches an interactive wizard that guides you through choosing an LLM provider, optional web search, and execution/safety preferences such as sandbox mode, bash access, and file-write tools. It generates a minimal config.yaml and writes your keys to .env. Takes about 2 minutes.

The wizard also lets you configure an optional web search provider, or skip it for now.

Run make doctor at any time to verify your setup and get actionable fix hints.

Advanced / manual configuration: If you prefer to edit config.yaml directly, run make config instead to copy the full template. See config.example.yaml for the complete reference including CLI-backed providers (Codex CLI, Claude Code OAuth), OpenRouter, Responses API, and more.
Manual model configuration examples
```
models:
  - name: gpt-4o
    display_name: GPT-4o
    use: langchain_openai:ChatOpenAI
    model: gpt-4o
    api_key: $OPENAI_API_KEY

  - name: openrouter-gemini-2.5-flash
    display_name: Gemini 2.5 Flash (OpenRouter)
    use: langchain_openai:ChatOpenAI
    model: google/gemini-2.5-flash-preview
    api_key: $OPENROUTER_API_KEY
    base_url: https://openrouter.ai/api/v1

  - name: gpt-5-responses
    display_name: GPT-5 (Responses API)
    use: langchain_openai:ChatOpenAI
    model: gpt-5
    api_key: $OPENAI_API_KEY
    use_responses_api: true
    output_version: responses/v1

  - name: qwen3-32b-vllm
    display_name: Qwen3 32B (vLLM)
    use: deerflow.models.vllm_provider:VllmChatModel
    model: Qwen/Qwen3-32B
    api_key: $VLLM_API_KEY
    base_url: http://localhost:8000/v1
    supports_thinking: true
    when_thinking_enabled:
      extra_body:
        chat_template_kwargs:
          enable_thinking: true
```
OpenRouter and similar OpenAI-compatible gateways should be configured with langchain_openai:ChatOpenAI plus base_url. If you prefer a provider-specific environment variable name, point api_key at that variable explicitly (for example api_key: $OPENROUTER_API_KEY).

To route OpenAI models through /v1/responses, keep using langchain_openai:ChatOpenAI and set use_responses_api: true with output_version: responses/v1.

For vLLM 0.19.0, use deerflow.models.vllm_provider:VllmChatModel. For Qwen-style reasoning models, DeerFlow toggles reasoning with extra_body.chat_template_kwargs.enable_thinking and preserves vLLM's non-standard reasoning field across multi-turn tool-call conversations. Legacy thinking configs are normalized automatically for backward compatibility. Reasoning models may also require the server to be started with --reasoning-parser .... If your local vLLM deployment accepts any non-empty API key, you can still set VLLM_API_KEY to a placeholder value.

CLI-backed provider examples:
```
models:
  - name: gpt-5.4
    display_name: GPT-5.4 (Codex CLI)
    use: deerflow.models.openai_codex_provider:CodexChatModel
    model: gpt-5.4
    supports_thinking: true
    supports_reasoning_effort: true

  - name: claude-sonnet-4.6
    display_name: Claude Sonnet 4.6 (Claude Code OAuth)
    use: deerflow.models.claude_provider:ClaudeChatModel
    model: claude-sonnet-4-6
    max_tokens: 4096
    supports_thinking: true
```
- Codex CLI reads ~/.codex/auth.json
- Claude Code accepts CLAUDE_CODE_OAUTH_TOKEN, ANTHROPIC_AUTH_TOKEN, CLAUDE_CODE_CREDENTIALS_PATH, or ~/.claude/.credentials.json
- ACP agent entries are separate from model providers — if you configure acp_agents.codex, point it at a Codex ACP adapter such as npx -y @zed-industries/codex-acp
- On macOS, export Claude Code auth explicitly if needed:
```
eval "$(python3 scripts/export_claude_code_oauth.py --print-export)"
```
API keys can also be set manually in .env (recommended) or exported in your shell:
```
OPENAI_API_KEY=your-openai-api-key
TAVILY_API_KEY=your-tavily-api-key
```

Running the Application

Deployment Sizing

Use the table below as a practical starting point when choosing how to run DeerFlow:

Deployment target	Starting point	Recommended	Notes
Local evaluation / `make dev`	4 vCPU, 8 GB RAM, 20 GB free SSD	8 vCPU, 16 GB RAM	Good for one developer or one light session with hosted model APIs. `2 vCPU / 4 GB` is usually not enough.
Docker development / `make docker-start`	4 vCPU, 8 GB RAM, 25 GB free SSD	8 vCPU, 16 GB RAM	Image builds, bind mounts, and sandbox containers need more headroom than pure local dev.
Long-running server / `make up`	8 vCPU, 16 GB RAM, 40 GB free SSD	16 vCPU, 32 GB RAM	Preferred for shared use, multi-agent runs, report generation, or heavier sandbox workloads.

These numbers cover DeerFlow itself. If you also host a local LLM, size that service separately.
Linux plus Docker is the recommended deployment target for a persistent server. macOS and Windows are best treated as development or evaluation environments.
If CPU or memory usage stays pinned, reduce concurrent runs first, then move to the next sizing tier.

Option 1: Docker (Recommended)

Development (hot-reload, source mounts):

make docker-init    # Pull sandbox image (only once or when image updates)
make docker-start   # Start services (auto-detects sandbox mode from config.yaml)

make docker-start starts provisioner only when config.yaml uses provisioner mode (sandbox.use: deerflow.community.aio_sandbox:AioSandboxProvider with provisioner_url).

Docker builds use the upstream uv registry by default. If you need faster mirrors in restricted networks, export UV_INDEX_URL=https://pypi.tuna.tsinghua.edu.cn/simple and NPM_REGISTRY=https://registry.npmmirror.com before running make docker-init or make docker-start.

Backend processes automatically pick up config.yaml changes on the next config access, so model metadata updates do not require a manual restart during development.

Tip

On Linux, if Docker-based commands fail with permission denied while trying to connect to the Docker daemon socket at unix:///var/run/docker.sock, add your user to the docker group and re-login before retrying. See CONTRIBUTING.md for the full fix.

Production (builds images locally, mounts runtime config and data):

make up     # Build images and start all production services
make down   # Stop and remove containers

Note

The LangGraph agent server currently runs via langgraph dev (the open-source CLI server).

Access: http://localhost:2026

See CONTRIBUTING.md for detailed Docker development guide.

Option 2: Local Development

If you prefer running services locally:

Prerequisite: complete the "Configuration" steps above first (make setup). make dev requires a valid config.yaml in the project root (can be overridden via DEER_FLOW_CONFIG_PATH). Run make doctor to verify your setup before starting. On Windows, run the local development flow from Git Bash. Native cmd.exe and PowerShell shells are not supported for the bash-based service scripts, and WSL is not guaranteed because some scripts rely on Git for Windows utilities such as cygpath.

Check prerequisites:

make check  # Verifies Node.js 22+, pnpm, uv, nginx

Install dependencies:

make install  # Install backend + frontend dependencies

(Optional) Pre-pull sandbox image:

# Recommended if using Docker/Container-based sandbox
make setup-sandbox

(Optional) Load sample memory data for local review:
```
python scripts/load_memory_sample.py
```
This copies the sample fixture into the default local runtime memory file so reviewers can immediately test Settings > Memory. See backend/docs/MEMORY_SETTINGS_REVIEW.md for the shortest review flow.
Start services:
```
make dev
```
Access: http://localhost:2026

Startup Modes

DeerFlow supports multiple startup modes across two dimensions:

Dev / Prod — dev enables hot-reload; prod uses pre-built frontend
Standard / Gateway — standard uses a separate LangGraph server (4 processes); Gateway mode (experimental) embeds the agent runtime in the Gateway API (3 processes)

	Local Foreground	Local Daemon	Docker Dev	Docker Prod
Dev	`./scripts/serve.sh --dev` `make dev`	`./scripts/serve.sh --dev --daemon` `make dev-daemon`	`./scripts/docker.sh start` `make docker-start`	—
Dev + Gateway	`./scripts/serve.sh --dev --gateway` `make dev-pro`	`./scripts/serve.sh --dev --gateway --daemon` `make dev-daemon-pro`	`./scripts/docker.sh start --gateway` `make docker-start-pro`	—
Prod	`./scripts/serve.sh --prod` `make start`	`./scripts/serve.sh --prod --daemon` `make start-daemon`	—	`./scripts/deploy.sh` `make up`
Prod + Gateway	`./scripts/serve.sh --prod --gateway` `make start-pro`	`./scripts/serve.sh --prod --gateway --daemon` `make start-daemon-pro`	—	`./scripts/deploy.sh --gateway` `make up-pro`

Action	Local	Docker Dev	Docker Prod
Stop	`./scripts/serve.sh --stop` `make stop`	`./scripts/docker.sh stop` `make docker-stop`	`./scripts/deploy.sh down` `make down`
Restart	`./scripts/serve.sh --restart [flags]`	`./scripts/docker.sh restart`	—

Gateway mode eliminates the LangGraph server process — the Gateway API handles agent execution directly via async tasks, managing its own concurrency.

Why Gateway Mode?

In standard mode, DeerFlow runs a dedicated LangGraph Platform server alongside the Gateway API. This architecture works well but has trade-offs:

	Standard Mode	Gateway Mode
Architecture	Gateway (REST API) + LangGraph (agent runtime)	Gateway embeds agent runtime
Concurrency	`--n-jobs-per-worker` per worker (requires license)	`--workers` × async tasks (no per-worker cap)
Containers / Processes	4 (frontend, gateway, langgraph, nginx)	3 (frontend, gateway, nginx)
Resource usage	Higher (two Python runtimes)	Lower (single Python runtime)
LangGraph Platform license	Required for production images	Not required
Cold start	Slower (two services to initialize)	Faster

Both modes are functionally equivalent — the same agents, tools, and skills work in either mode.

Docker Production Deployment

deploy.sh supports building and starting separately. Images are mode-agnostic — runtime mode is selected at start time:

# One-step (build + start)
deploy.sh                    # standard mode (default)
deploy.sh --gateway          # gateway mode

# Two-step (build once, start with any mode)
deploy.sh build              # build all images
deploy.sh start              # start in standard mode
deploy.sh start --gateway    # start in gateway mode

# Stop
deploy.sh down

Advanced

Sandbox Mode

DeerFlow supports multiple sandbox execution modes:

Local Execution (runs sandbox code directly on the host machine)
Docker Execution (runs sandbox code in isolated Docker containers)
Docker Execution with Kubernetes (runs sandbox code in Kubernetes pods via provisioner service)

For Docker development, service startup follows config.yaml sandbox mode. In Local/Docker modes, provisioner is not started.

See the Sandbox Configuration Guide to configure your preferred mode.

MCP Server

DeerFlow supports configurable MCP servers and skills to extend its capabilities. For HTTP/SSE MCP servers, OAuth token flows are supported (client_credentials, refresh_token). See the MCP Server Guide for detailed instructions.

IM Channels

DeerFlow supports receiving tasks from messaging apps. Channels auto-start when configured — no public IP required for any of them.

Channel	Transport	Difficulty
Telegram	Bot API (long-polling)	Easy
Slack	Socket Mode	Moderate
Feishu / Lark	WebSocket	Moderate
WeChat	Tencent iLink (long-polling)	Moderate
WeCom	WebSocket	Moderate

Configuration in config.yaml:

channels:
  # LangGraph Server URL (default: http://localhost:2024)
  langgraph_url: http://localhost:2024
  # Gateway API URL (default: http://localhost:8001)
  gateway_url: http://localhost:8001

  # Optional: global session defaults for all mobile channels
  session:
    assistant_id: lead_agent  # or a custom agent name; custom agents are routed via lead_agent + agent_name
    config:
      recursion_limit: 100
    context:
      thinking_enabled: true
      is_plan_mode: false
      subagent_enabled: false

  feishu:
    enabled: true
    app_id: $FEISHU_APP_ID
    app_secret: $FEISHU_APP_SECRET
    # domain: https://open.feishu.cn       # China (default)
    # domain: https://open.larksuite.com   # International

  wecom:
    enabled: true
    bot_id: $WECOM_BOT_ID
    bot_secret: $WECOM_BOT_SECRET

  slack:
    enabled: true
    bot_token: $SLACK_BOT_TOKEN     # xoxb-...
    app_token: $SLACK_APP_TOKEN     # xapp-... (Socket Mode)
    allowed_users: []               # empty = allow all

  telegram:
    enabled: true
    bot_token: $TELEGRAM_BOT_TOKEN
    allowed_users: []               # empty = allow all

  wechat:
    enabled: false
    bot_token: $WECHAT_BOT_TOKEN
    ilink_bot_id: $WECHAT_ILINK_BOT_ID
    qrcode_login_enabled: true      # optional: allow first-time QR bootstrap when bot_token is absent
    allowed_users: []               # empty = allow all
    polling_timeout: 35
    state_dir: ./.deer-flow/wechat/state
    max_inbound_image_bytes: 20971520
    max_outbound_image_bytes: 20971520
    max_inbound_file_bytes: 52428800
    max_outbound_file_bytes: 52428800

    # Optional: per-channel / per-user session settings
    session:
      assistant_id: mobile-agent  # custom agent names are also supported here
      context:
        thinking_enabled: false
      users:
        "123456789":
          assistant_id: vip-agent
          config:
            recursion_limit: 150
          context:
            thinking_enabled: true
            subagent_enabled: true

Notes:

assistant_id: lead_agent calls the default LangGraph assistant directly.
If assistant_id is set to a custom agent name, DeerFlow still routes through lead_agent and injects that value as agent_name, so the custom agent's SOUL/config takes effect for IM channels.

Set the corresponding API keys in your .env file:

# Telegram
TELEGRAM_BOT_TOKEN=123456789:ABCdefGHIjklMNOpqrSTUvwxYZ

# Slack
SLACK_BOT_TOKEN=xoxb-...
SLACK_APP_TOKEN=xapp-...

# Feishu / Lark
FEISHU_APP_ID=cli_xxxx
FEISHU_APP_SECRET=your_app_secret

# WeChat iLink
WECHAT_BOT_TOKEN=your_ilink_bot_token
WECHAT_ILINK_BOT_ID=your_ilink_bot_id

# WeCom
WECOM_BOT_ID=your_bot_id
WECOM_BOT_SECRET=your_bot_secret

Telegram Setup

Chat with @BotFather, send /newbot, and copy the HTTP API token.
Set TELEGRAM_BOT_TOKEN in .env and enable the channel in config.yaml.

Slack Setup

Create a Slack App at api.slack.com/apps → Create New App → From scratch.
Under OAuth & Permissions, add Bot Token Scopes: app_mentions:read, chat:write, im:history, im:read, im:write, files:write.
Enable Socket Mode → generate an App-Level Token (xapp-…) with connections:write scope.
Under Event Subscriptions, subscribe to bot events: app_mention, message.im.
Set SLACK_BOT_TOKEN and SLACK_APP_TOKEN in .env and enable the channel in config.yaml.

Feishu / Lark Setup

Create an app on Feishu Open Platform → enable Bot capability.
Add permissions: im:message, im:message.p2p_msg:readonly, im:resource.
Under Events, subscribe to im.message.receive_v1 and select Long Connection mode.
Copy the App ID and App Secret. Set FEISHU_APP_ID and FEISHU_APP_SECRET in .env and enable the channel in config.yaml.

WeChat Setup

Enable the wechat channel in config.yaml.
Either set WECHAT_BOT_TOKEN in .env, or set qrcode_login_enabled: true for first-time QR bootstrap.
When bot_token is absent and QR bootstrap is enabled, watch backend logs for the QR content returned by iLink and complete the binding flow.
After the QR flow succeeds, DeerFlow persists the acquired token under state_dir for later restarts.
For Docker Compose deployments, keep state_dir on a persistent volume so the get_updates_buf cursor and saved auth state survive restarts.

WeCom Setup

Create a bot on the WeCom AI Bot platform and obtain the bot_id and bot_secret.
Enable channels.wecom in config.yaml and fill in bot_id / bot_secret.
Set WECOM_BOT_ID and WECOM_BOT_SECRET in .env.
Make sure backend dependencies include wecom-aibot-python-sdk. The channel uses a WebSocket long connection and does not require a public callback URL.
The current integration supports inbound text, image, and file messages. Final images/files generated by the agent are also sent back to the WeCom conversation.

When DeerFlow runs in Docker Compose, IM channels execute inside the gateway container. In that case, do not point channels.langgraph_url or channels.gateway_url at localhost; use container service names such as http://langgraph:2024 and http://gateway:8001, or set DEER_FLOW_CHANNELS_LANGGRAPH_URL and DEER_FLOW_CHANNELS_GATEWAY_URL.

Commands

Once a channel is connected, you can interact with DeerFlow directly from the chat:

Command	Description
`/new`	Start a new conversation
`/status`	Show current thread info
`/models`	List available models
`/memory`	View memory
`/help`	Show help

Messages without a command prefix are treated as regular chat — DeerFlow creates a thread and responds conversationally.

LangSmith Tracing

DeerFlow has built-in LangSmith integration for observability. When enabled, all LLM calls, agent runs, and tool executions are traced and visible in the LangSmith dashboard.

Add the following to your .env file:

LANGSMITH_TRACING=true
LANGSMITH_ENDPOINT=https://api.smith.langchain.com
LANGSMITH_API_KEY=lsv2_pt_xxxxxxxxxxxxxxxx
LANGSMITH_PROJECT=xxx

Langfuse Tracing

DeerFlow also supports Langfuse observability for LangChain-compatible runs.

Add the following to your .env file:

LANGFUSE_TRACING=true
LANGFUSE_PUBLIC_KEY=pk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_SECRET_KEY=sk-lf-xxxxxxxxxxxxxxxx
LANGFUSE_BASE_URL=https://cloud.langfuse.com

If you are using a self-hosted Langfuse instance, set LANGFUSE_BASE_URL to your deployment URL.

Using Both Providers

If both LangSmith and Langfuse are enabled, DeerFlow attaches both tracing callbacks and reports the same model activity to both systems.

If a provider is explicitly enabled but missing required credentials, or if its callback fails to initialize, DeerFlow fails fast when tracing is initialized during model creation and the error message names the provider that caused the failure.

For Docker deployments, tracing is disabled by default. Set LANGSMITH_TRACING=true and LANGSMITH_API_KEY in your .env to enable it.

From Deep Research to Super Agent Harness

DeerFlow started as a Deep Research framework — and the community ran with it. Since launch, developers have pushed it far beyond research: building data pipelines, generating slide decks, spinning up dashboards, automating content workflows. Things we never anticipated.

That told us something important: DeerFlow wasn't just a research tool. It was a harness — a runtime that gives agents the infrastructure to actually get work done.

So we rebuilt it from scratch.

DeerFlow 2.0 is no longer a framework you wire together. It's a super agent harness — batteries included, fully extensible. Built on LangGraph and LangChain, it ships with everything an agent needs out of the box: a filesystem, memory, skills, sandbox-aware execution, and the ability to plan and spawn sub-agents for complex, multi-step tasks.

Use it as-is. Or tear it apart and make it yours.

Core Features

Skills & Tools

Skills are what make DeerFlow do almost anything.

A standard Agent Skill is a structured capability module — a Markdown file that defines a workflow, best practices, and references to supporting resources. DeerFlow ships with built-in skills for research, report generation, slide creation, web pages, image and video generation, and more. But the real power is extensibility: add your own skills, replace the built-in ones, or combine them into compound workflows.

Skills are loaded progressively — only when the task needs them, not all at once. This keeps the context window lean and makes DeerFlow work well even with token-sensitive models.

When you install .skill archives through the Gateway, DeerFlow accepts standard optional frontmatter metadata such as version, author, and compatibility instead of rejecting otherwise valid external skills.

Tools follow the same philosophy. DeerFlow comes with a core toolset — web search, web fetch, file operations, bash execution — and supports custom tools via MCP servers and Python functions. Swap anything. Add anything.

Gateway-generated follow-up suggestions now normalize both plain-string model output and block/list-style rich content before parsing the JSON array response, so provider-specific content wrappers do not silently drop suggestions.

# Paths inside the sandbox container
/mnt/skills/public
├── research/SKILL.md
├── report-generation/SKILL.md
├── slide-creation/SKILL.md
├── web-page/SKILL.md
└── image-generation/SKILL.md

/mnt/skills/custom
└── your-custom-skill/SKILL.md      ← yours

Claude Code Integration

The claude-to-deerflow skill lets you interact with a running DeerFlow instance directly from Claude Code. Send research tasks, check status, manage threads — all without leaving the terminal.

Install the skill:

npx skills add https://github.com/bytedance/deer-flow --skill claude-to-deerflow

Then make sure DeerFlow is running (default at http://localhost:2026) and use the /claude-to-deerflow command in Claude Code.

What you can do:

Send messages to DeerFlow and get streaming responses
Choose execution modes: flash (fast), standard, pro (planning), ultra (sub-agents)
Check DeerFlow health, list models/skills/agents
Manage threads and conversation history
Upload files for analysis

Environment variables (optional, for custom endpoints):

DEERFLOW_URL=http://localhost:2026            # Unified proxy base URL
DEERFLOW_GATEWAY_URL=http://localhost:2026    # Gateway API
DEERFLOW_LANGGRAPH_URL=http://localhost:2026/api/langgraph  # LangGraph API

See skills/public/claude-to-deerflow/SKILL.md for the full API reference.

Sub-Agents

Complex tasks rarely fit in a single pass. DeerFlow decomposes them.

The lead agent can spawn sub-agents on the fly — each with its own scoped context, tools, and termination conditions. Sub-agents run in parallel when possible, report back structured results, and the lead agent synthesizes everything into a coherent output.

This is how DeerFlow handles tasks that take minutes to hours: a research task might fan out into a dozen sub-agents, each exploring a different angle, then converge into a single report — or a website — or a slide deck with generated visuals. One harness, many hands.

Sandbox & File System

DeerFlow doesn't just talk about doing things. It has its own computer.

Each task gets its own execution environment with a full filesystem view — skills, workspace, uploads, outputs. The agent reads, writes, and edits files. It can view images and, when configured safely, execute shell commands.

With AioSandboxProvider, shell execution runs inside isolated containers. With LocalSandboxProvider, file tools still map to per-thread directories on the host, but host bash is disabled by default because it is not a secure isolation boundary. Re-enable host bash only for fully trusted local workflows.

This is the difference between a chatbot with tool access and an agent with an actual execution environment.

# Paths inside the sandbox container
/mnt/user-data/
├── uploads/          ← your files
├── workspace/        ← agents' working directory
└── outputs/          ← final deliverables

Context Engineering

Isolated Sub-Agent Context: Each sub-agent runs in its own isolated context. This means that the sub-agent will not be able to see the context of the main agent or other sub-agents. This is important to ensure that the sub-agent is able to focus on the task at hand and not be distracted by the context of the main agent or other sub-agents.

Summarization: Within a session, DeerFlow manages context aggressively — summarizing completed sub-tasks, offloading intermediate results to the filesystem, compressing what's no longer immediately relevant. This lets it stay sharp across long, multi-step tasks without blowing the context window.

Strict Tool-Call Recovery: When a provider or middleware interrupts a tool-call loop, DeerFlow now strips provider-level raw tool-call metadata on forced-stop assistant messages and injects placeholder tool results for dangling calls before the next model invocation. This keeps OpenAI-compatible reasoning models that strictly validate tool_call_id sequences from failing with malformed history errors.

Long-Term Memory

Most agents forget everything the moment a conversation ends. DeerFlow remembers.

Across sessions, DeerFlow builds a persistent memory of your profile, preferences, and accumulated knowledge. The more you use it, the better it knows you — your writing style, your technical stack, your recurring workflows. Memory is stored locally and stays under your control.

Memory updates now skip duplicate fact entries at apply time, so repeated preferences and context do not accumulate endlessly across sessions.

Recommended Models

DeerFlow is model-agnostic — it works with any LLM that implements the OpenAI-compatible API. That said, it performs best with models that support:

Long context windows (100k+ tokens) for deep research and multi-step tasks
Reasoning capabilities for adaptive planning and complex decomposition
Multimodal inputs for image understanding and video comprehension
Strong tool-use for reliable function calling and structured outputs

Embedded Python Client

DeerFlow can be used as an embedded Python library without running the full HTTP services. The DeerFlowClient provides direct in-process access to all agent and Gateway capabilities, returning the same response schemas as the HTTP Gateway API. The HTTP Gateway also exposes DELETE /api/threads/{thread_id} to remove DeerFlow-managed local thread data after the LangGraph thread itself has been deleted:

from deerflow.client import DeerFlowClient

client = DeerFlowClient()

# Chat
response = client.chat("Analyze this paper for me", thread_id="my-thread")

# Streaming (LangGraph SSE protocol: values, messages-tuple, end)
for event in client.stream("hello"):
    if event.type == "messages-tuple" and event.data.get("type") == "ai":
        print(event.data["content"])

# Configuration & management — returns Gateway-aligned dicts
models = client.list_models()        # {"models": [...]}
skills = client.list_skills()        # {"skills": [...]}
client.update_skill("web-search", enabled=True)
client.upload_files("thread-1", ["./report.pdf"])  # {"success": True, "files": [...]}

All dict-returning methods are validated against Gateway Pydantic response models in CI (TestGatewayConformance), ensuring the embedded client stays in sync with the HTTP API schemas. See backend/packages/harness/deerflow/client.py for full API documentation.

Documentation

Contributing Guide - Development environment setup and workflow
Configuration Guide - Setup and configuration instructions
Architecture Overview - Technical architecture details
Backend Architecture - Backend architecture and API reference

⚠️ Security Notice

Improper Deployment May Introduce Security Risks

DeerFlow has key high-privilege capabilities including system command execution, resource operations, and business logic invocation, and is designed by default to be deployed in a local trusted environment (accessible only via the 127.0.0.1 loopback interface). If you deploy the agent in untrusted environments — such as LAN networks, public cloud servers, or other multi-endpoint accessible environments — without strict security measures, it may introduce security risks, including:

Unauthorized illegal invocation: Agent functionality could be discovered by unauthorized third parties or malicious internet scanners, triggering bulk unauthorized requests that execute high-risk operations such as system commands and file read/write, potentially causing serious security consequences.
Compliance and legal risks: If the agent is illegally invoked to conduct cyberattacks, data theft, or other illegal activities, it may result in legal liability and compliance risks.

Security Recommendations

Note: We strongly recommend deploying DeerFlow in a local trusted network environment. If you need cross-device or cross-network deployment, you must implement strict security measures, such as:

IP allowlist: Use iptables, or deploy hardware firewalls / switches with Access Control Lists (ACL), to configure IP allowlist rules and deny access from all other IP addresses.
Authentication gateway: Configure a reverse proxy (e.g., nginx) and enable strong pre-authentication, blocking any unauthenticated access.
Network isolation: Where possible, place the agent and trusted devices in the same dedicated VLAN, isolated from other network devices.
Stay updated: Continue to follow DeerFlow's security feature updates.

Contributing

We welcome contributions! Please see CONTRIBUTING.md for development setup, workflow, and guidelines.

Regression coverage includes Docker sandbox mode detection and provisioner kubeconfig-path handling tests in backend/tests/. Gateway artifact serving now forces active web content types (text/html, application/xhtml+xml, image/svg+xml) to download as attachments instead of inline rendering, reducing XSS risk for generated artifacts.

License

This project is open source and available under the MIT License.

Acknowledgments

DeerFlow is built upon the incredible work of the open-source community. We are deeply grateful to all the projects and contributors whose efforts have made DeerFlow possible. Truly, we stand on the shoulders of giants.

We would like to extend our sincere appreciation to the following projects for their invaluable contributions:

LangChain: Their exceptional framework powers our LLM interactions and chains, enabling seamless integration and functionality.
LangGraph: Their innovative approach to multi-agent orchestration has been instrumental in enabling DeerFlow's sophisticated workflows.

These projects exemplify the transformative power of open-source collaboration, and we are proud to build upon their foundations.

Key Contributors

A heartfelt thank you goes out to the core authors of DeerFlow, whose vision, passion, and dedication have brought this project to life:

Daniel Walnut
Henry Li

Your unwavering commitment and expertise have been the driving force behind DeerFlow's success. We are honored to have you at the helm of this journey.

Star History

siddharthvaddem/openscreen

Create stunning demos for free. Open-source, no subscriptions, no watermarks, and free for commercial use. An alternative to Screen Studio.

Warning

This is very much in beta and might be buggy here and there (but hope you have a good experience!).

OpenScreen

OpenScreen is your free, open-source alternative to Screen Studio (sort of).

If you don't want to pay $29/month for Screen Studio but want a much simpler version that does what most people seem to need, making beautiful product demos and walkthroughs, here's a free-to-use app for you. OpenScreen does not offer all Screen Studio features, but covers the basics well!

Screen Studio is an awesome product and this is definitely not a 1:1 clone. OpenScreen is a much simpler take, just the basics for folks who want control and don't want to pay. If you need all the fancy features, your best bet is to support Screen Studio (they really do a great job, haha). But if you just want something free (no gotchas) and open, this project does the job!

OpenScreen is 100% free for personal and commercial use. Use it, modify it, distribute it. (Just be cool 😁 and give a shoutout if you feel like it !)

Core Features

Record specific windows or your whole screen.
Add automatic or manual zooms (adjustable depth levels) and customize their durarion and position.
Record microphone and system audio.
Crop video recordings to hide parts.
Choose between wallpapers, solid colors, gradients or a custom background.
Motion blur for smoother pan and zoom effects.
Add annotations (text, arrows, images).
Trim sections of the clip.
Customize the speed of different segments.
Export in different aspect ratios and resolutions.

Installation

Download the latest installer for your platform from the GitHub Releases page.

macOS

If you encounter issues with macOS Gatekeeper blocking the app (since it does not come with a developer certificate), you can bypass this by running the following command in your terminal after installation:

xattr -rd com.apple.quarantine /Applications/Openscreen.app

Note: Give your terminal Full Disk Access in System Settings > Privacy & Security to grant you access and then run the above command.

After running this command, proceed to System Preferences > Security & Privacy to grant the necessary permissions for "screen recording" and "accessibility". Once permissions are granted, you can launch the app.

Linux

Download the .AppImage file from the releases page. Make it executable and run:

chmod +x Openscreen-Linux-*.AppImage
./Openscreen-Linux-*.AppImage

You may need to grant screen recording permissions depending on your desktop environment.

Note: If the app fails to launch due to a "sandbox" error, run it with --no-sandbox:

./Openscreen-Linux-*.AppImage --no-sandbox

Limitations

System audio capture relies on Electron's desktopCapturer and has some platform-specific quirks:

macOS: Requires macOS 13+. On macOS 14.2+ you'll be prompted to grant audio capture permission. macOS 12 and below does not support system audio (mic still works).
Windows: Works out of the box.
Linux: Needs PipeWire (default on Ubuntu 22.04+, Fedora 34+). Older PulseAudio-only setups may not support system audio (mic should still work).

Built with

Electron
React
TypeScript
Vite
PixiJS
dnd-timeline

I'm new to open source, idk what I'm doing lol. If something is wrong please raise an issue 🙏

Documentation

See the documentation here: OpenScreen Docs

Contributing

Contributions are welcome! If you’d like to help out or see what’s currently being worked on, take a look at the open issues and the project roadmap to understand the current direction of the project and find ways to contribute.

License

This project is licensed under the MIT License. By using this software, you agree that the authors are not liable for any issues, damages, or claims arising from its use.

FujiwaraChoki/MoneyPrinterV2

Automate the process of making money online.

MoneyPrinter V2

Features

Twitter Bot (with CRON Jobs => scheduler)
YouTube Shorts Automator (with CRON Jobs => scheduler)
Affiliate Marketing (Amazon + Twitter)
Find local businesses & cold outreach

Versions

MoneyPrinter has different versions for multiple languages developed by the community for the community. Here are some known versions:

Chinese: MoneyPrinterTurbo

If you would like to submit your own version/fork of MoneyPrinter, please open an issue describing the changes you made to the fork.

Installation

⚠️ If you are planning to reach out to scraped businesses per E-Mail, please first install the Go Programming Language.

git clone https://github.com/FujiwaraChoki/MoneyPrinterV2.git

cd MoneyPrinterV2
# Copy Example Configuration and fill out values in config.json
cp config.example.json config.json

# Create a virtual environment
python -m venv venv

# Activate the virtual environment - Windows
.\venv\Scripts\activate

# Activate the virtual environment - Unix
source venv/bin/activate

# Install the requirements
pip install -r requirements.txt

Usage

# Run the application
python src/main.py

Documentation

All relevant documents can be found here.

Scripts

For easier usage, there are some scripts in the scripts directory that can be used to directly access the core functionality of MPV2 without the need for user interaction.

All scripts need to be run from the root directory of the project, e.g. bash scripts/upload_video.sh.

Contributing

Please read CONTRIBUTING.md for details on our code of conduct, and the process for submitting pull requests to us. Check out docs/Roadmap.md for a list of features that need to be implemented.

Code of Conduct

Please read CODE_OF_CONDUCT.md for details on our code of conduct, and the process for submitting pull requests to us.

License

MoneyPrinterV2 is licensed under Affero General Public License v3.0. See LICENSE for more information.

Acknowledgments

Disclaimer

This project is for educational purposes only. The author will not be responsible for any misuse of the information provided. All the information on this website is published in good faith and for general information purposes only. The author does not make any warranties about the completeness, reliability, and accuracy of this information. Any action you take upon the information you find on this website (FujiwaraChoki/MoneyPrinterV2) is strictly at your own risk. The author will not be liable for any losses and/or damages in connection with the use of our website.

google-ai-edge/gallery

A gallery that showcases on-device ML/GenAI use cases and allows people to try and use models locally.

Google AI Edge Gallery ✨

Explore, Experience, and Evaluate the Future of On-Device Generative AI with Google AI Edge.

AI Edge Gallery is the premier destination for running the world's most powerful open-source Large Language Models (LLMs) on your mobile device. Experience high-performance Generative AI directly on your hardware—fully offline, private, and lightning-fast.

Now Featuring: Gemma 4

The latest version brings official support for the newly released Gemma 4 family. As the centerpiece of this release, Gemma 4 allows you to test the cutting edge of on-device AI. Experience advanced reasoning, logic, and creative capabilities without ever sending your data to a server.

Install the app today from Google Play	Install the app today from App Store

For users without Google Play access, install the apk from the latest release

App Preview

✨ Core Features

Agent Skills: Transform your LLM from a conversationalist into a proactive assistant. Use the Agent Skills tile to augment model capabilities with tools like Wikipedia for fact-grounding, interactive maps, and rich visual summary cards. You can even load modular skills from a URL or browse community contributions on GitHub Discussions.
AI Chat with Thinking Mode: Engage in fluid, multi-turn conversations and toggle the new Thinking Mode to peek "under the hood." This feature allows you to see the model’s step-by-step reasoning process, which is perfect for understanding complex problem-solving. Note: Thinking Mode currently works with supported models, starting with the Gemma 4 family.
Ask Image: Use multimodal power to identify objects, solve visual puzzles, or get detailed descriptions using your device’s camera or photo gallery.
Audio Scribe: Transcribe and translate voice recordings into text in real-time using high-efficiency on-device language models.
Prompt Lab: A dedicated workspace to test different prompts and single-turn use cases with granular control over model parameters like temperature and top-k.
Mobile Actions: Unlock offline device controls and automated tasks powered entirely by a finetune of FuntionGemma 270m.
Tiny Garden: A fun, experimental mini-game that uses natural language to plant and harvest a virtual garden using a finetune of FunctionGemma 270m.
Model Management & Benchmark: Gallery is a flexible sandbox for a wide variety of open-source models. Easily download models from the list or load your own custom models. Manage your model library effortlessly and run benchmark tests to understand exactly how each model performs on your specific hardware.
100% On-Device Privacy: All model inferences happen directly on your device hardware. No internet is required, ensuring total privacy for your prompts, images, and sensitive data.

🏁 Get Started in Minutes!

Check OS Requirement: Android 12 and up, and iOS 17 and up.
Download the App:
- Install the app from Google Play or App Store.
- For users without Google Play access: install the apk from the latest release
Install & Explore: For detailed installation instructions (including for corporate devices) and a full user guide, head over to our Project Wiki!

🛠️ Technology Highlights

Google AI Edge: Core APIs and tools for on-device ML.
LiteRT: Lightweight runtime for optimized model execution.
Hugging Face Integration: For model discovery and download.

⌨️ Development

Check out the development notes for instructions about how to build the app locally.

🤝 Feedback

This is an experimental Beta release, and your input is crucial!

🐞 Found a bug? Report it here!
💡 Have an idea? Suggest a feature!

📄 License

Licensed under the Apache License, Version 2.0. See the LICENSE file for details.

🔗 Useful Links

mvanhorn/last30days-skill

AI agent skill that researches any topic across Reddit, X, YouTube, HN, Polymarket, and the web - then synthesizes a grounded summary

/last30days

An AI agent-led search engine scored by upvotes, likes, and real money - not editors.

This README tracks the current v3 pipeline. The runtime skill spec lives in skills/last30days/SKILL.md, which is the source of truth for the latest command and setup behavior.

Claude Code:

/plugin marketplace add mvanhorn/last30days-skill

OpenClaw:

clawhub install last30days-official

Hermes:

# The skill auto-deploys when you run sync.sh
# Or manually copy to ~/.hermes/skills/research/last30days/

Zero config. Reddit, HN, Polymarket, and GitHub work immediately. Run it once and the setup wizard unlocks X, YouTube, TikTok, and more in 30 seconds.

Reddit upvotes. X likes. YouTube transcripts. TikTok engagement. Polymarket odds backed by real money and insider information. That's millions of people voting with their attention and their wallets every day. /last30days searches all of it in parallel, scores it by what real people actually engage with, and an AI agent judge synthesizes it into one brief.

Google aggregates editors. /last30days searches people.

You can't get this search anywhere else because no single AI has access to all of it. Google search doesn't touch Reddit comments or X posts. ChatGPT has a deal with Reddit but can't search X or TikTok. Gemini has YouTube but not Reddit. Claude has none of them natively. Each platform is a walled garden with its own API, its own tokens, its own auth. But you can bring your own keys and browser sessions, and suddenly an AI agent can search all of them at once, score them against each other, and tell you what actually matters.

That's the unlock. Not one better search engine. A dozen disconnected platforms, bridged by an agent.

/last30days Peter Steinberger

You have a meeting tomorrow. You Google them. You get their LinkedIn from 2023. /last30days gives you what they're actually doing this month: joined OpenAI to work on Codex, fighting Anthropic's ban on third-party agents, shipping 23 PRs at 85% merge rate, building "LobsterOS" for cross-device agent control, and r/ClaudeCode hit 569 upvotes debating whether he's a hero or "insufferable." Scattered across X posts, Reddit threads, YouTube transcripts, and GitHub commits. None of it was on Google.

Why this exists

I built it to keep up in AI. Everything changes every day and the Reddit and X nerds are always on top of it first. I needed better prompts, and the training data was always months behind what the community had already figured out.

But it turned into something bigger. Now I run it before a sales call to know the last 30 days truth about a business. Before a meeting to read someone's recent tweets and podcast transcripts. Before a Disney World trip to know which rides are closed and what the community says about Genie+. Before I build anything to know what problems people are actually hitting.

If you're meeting with a CEO, have you read all their tweets and YouTube transcripts from the last 30 days? I have.

Sources, scored by the people

Source	What the people tell you
Reddit	The unfiltered take. Top comments with upvote counts, free via public JSON. The real opinions that Google buries.
X / Twitter	The hot take, the expert thread, the breaking reaction. First to know, first to argue.
YouTube	The 45-minute deep dive. Full transcripts searched for the 5 quotable sentences that matter.
TikTok	The creator reaching 3.6M people with a take you'll never find on Google.
Instagram Reels	The influencer perspective with spoken-word transcripts. The visual culture signal.
Hacker News	The developer consensus. 825 points, 899 comments. Where technical people actually argue.
Polymarket	Not opinions. Odds. Backed by real money. 96% confidence on album sales. 4% on an acquisition.
GitHub	For people: PR velocity, top repos by stars, release notes. For topics: issues and discussions.
Threads	The post-Twitter text layer. Conversations from creators and brands.
Pinterest	Visual discovery. Pins, saves, and comments on products and ideas.
Bluesky	The decentralized social layer. AT Protocol posts from the post-Twitter migration.
Perplexity	Grounded web search with citations via Sonar Pro.
Web	The editorial coverage, the blog comparisons. One signal of many, not the only one.

Community contributors keep adding more. Truth Social, Xiaohongshu (RED), and others are in the engine with more on the way.

A Reddit thread with 1,500 upvotes is a stronger signal than a blog post nobody read. A TikTok with 3.6M views tells you more about what's culturally relevant than a press release. Polymarket odds backed by $66K in volume are harder to argue with than a pundit's guess.

The synthesis ranks by what real people actually engaged with. Social relevancy, not SEO relevancy.

What people actually use it for

Before a meeting. /last30days Peter Steinberger - joined OpenAI's Codex team, fighting Anthropic's ban on third-party agents, 23 PRs merged at 85% merge rate on GitHub, building LobsterOS for cross-device agent control. r/ClaudeCode: "Ever since OpenClaw released, it was widely known that if you run it through anything other than the API, you were gonna get banned eventually" (227 upvotes). That's not on LinkedIn.

When something drops. /last30days Kanye West - UK blocked his visa, Wireless Festival canceled, sponsors fled. But BULLY debuted #2 on Billboard. Fantano came back from his "Yay sabbatical" to review it (653K views). SoFi Homecoming brought out Lauryn Hill and Travis Scott for 44 songs. Polymarket: "Will Kanye tweet again?" 86% Yes. 23 Reddit threads, 17 YouTube videos, 86K upvotes.

To compare tools. /last30days OpenClaw vs Hermes vs Paperclip - "These aren't competitors, they're layers." OpenClaw is the executor (351K GitHub stars, live), Hermes is the self-improving brain (31K stars), Paperclip is the org chart (49K stars). Star counts pulled live from the GitHub API, not stale blog posts. Side-by-side table with architecture, memory, security, best-for. Per @IMJustinBrooke: "OpenClaw = Charmander, Hermes = Charizard."

To understand the world. /last30days Iran vs USA - Day 38 of the war. Trump's Tuesday deadline for Iran to reopen the Strait of Hormuz. Two US warplanes downed. Oil at $126/barrel. The IEA called it "the largest supply disruption in the history of the global oil market." Polymarket: ceasefire by Dec 31 at 74%. 27 X posts, 10 YouTube videos, 20 prediction markets.

Before a trip. /last30days Universal Epic Universe - Expansion already under construction. "Project 680" permit filed. Fireworks show confirmed by infrastructure but unannounced. Wait times: Mine-Cart Madness averaging 148 minutes. No annual pass yet, and locals are frustrated. Stardust Racers down for refurbishment through April 5.

To learn something fast. /last30days Nano Banana Pro prompting - JSON-structured prompts are replacing tag soup. @pictsbyai's nested format prevents "concept bleeding." Edit-first workflow beats regeneration. Then it writes you a production prompt using exactly what the community said works.

What v3 Changed

Intelligent search: the killer feature

The v3 engine doesn't just search for your topic. It figures out where to search before the search begins. Type "OpenClaw" and the engine resolves @steipete (Peter Steinberger, the creator), r/openclaw, r/ClaudeCode, and the right YouTube channels and TikTok hashtags - all via a new Python pre-research brain built by @j-sperling. The old engine searched keywords. The new engine understands your topic first, then searches the right people and communities.

This is why v3 finds content v2 never could. "Paperclip" resolves @dotta. "Dave Morin" resolves @davemorin plus @OpenClaw plus the TWiST podcast. "Peter Steinberger" resolves @steipete on X and steipete on GitHub. Bidirectional: person to company, product to founder, name to GitHub profile. The right subreddits, the right handles, the right hashtags - resolved before a single API call fires.

Best Takes

Reddit and X people are funny. The old engine buried their best stuff because it scored for relevance, not cleverness. v3 has a second judge that scores every result for humor, wit, and virality alongside the relevance score. Tommy Lloyd's "My Michael Jordan is Steve Kerr" scores low on relevance to "Arizona Basketball" but off the charts on fun. Now every brief ends with a "Best Takes" section - the cleverest one-liners, the most viral quotes, the reactions that make you want to share the research. Built in, not a toggle.

Cross-source cluster merging

When the same story appears on Reddit, X, and YouTube, v3 merges them into one cluster instead of showing three separate items. Entity-based overlap detection catches matches even when the titles use different words.

Single-pass comparisons

"CLI vs MCP" used to run three serial passes (12+ minutes). v3 runs one pass with entity-aware subqueries for both sides simultaneously. Same depth, 3 minutes.

GitHub person-mode

When the topic is a person, the engine switches from keyword search to author-scoped queries. Instead of "who mentioned this name in an issue body," it answers: what are they shipping and where is it landing?

/last30days Peter Steinberger --github-user=steipete shows 22 PRs merged across 3 repos at 85% merge rate. Own projects with README summaries, star counts, and top feature requests. Release notes for what shipped this month. The synthesizer weaves it into the narrative alongside X posts and Reddit threads.

ELI5 mode

Say "eli5 on" after any research run. The synthesis rewrites in plain language. No jargon. Same data, same sources, same citations - just clearer. "Arizona wins by being physical" instead of "Arizona's identity is paint scoring (50%+ shooting, 9th nationally)." Say "eli5 off" to go back.

Everything else in v3

Free Reddit comments. Public JSON gives you threads + top comments with upvote counts. No API key, no ScrapeCreators. Just works.
YouTube transcripts that actually work. Widened candidate pool 3x past music videos to reach talk/review content with captions.
Threads, Pinterest, YouTube + TikTok comments. Opt-in sources via ScrapeCreators. Set INCLUDE_SOURCES=tiktok,instagram and add threads, pinterest, youtube_comments, tiktok_comments for more. youtube_comments and tiktok_comments surface top comments with vote counts the same way Reddit does.
Perplexity Sonar. Grounded web search with citations via OpenRouter. Add OPENROUTER_API_KEY to unlock.
Polymarket noise filtering. Common-word disambiguation prevents "Apple" from matching "Will Apple release a car?"
Resilient Reddit. Timeout budgets and runtime fallback. One slow thread doesn't kill the whole run.
Fun judge v2. Humor scoring baked into the narrative. Reddit's cleverest one-liners mixed into the synthesis where they fit, not dumped in a separate section.
Polymarket odds, not dollars. The % odds are the magic. Dollar volumes removed from display.
Per-author cap. Max 3 items per author prevents any single voice from dominating your brief.
Entity disambiguation. When the engine resolves handles, the synthesis trusts them. No more Mallorca resorts winning over Washington athletic clubs.
OpenClaw first-class citizen. Auto-resolve for engine-side pre-research. Device auth for frictionless ScrapeCreators signup.
1,012 tests passing.

Install

Surface	Install
claude.ai (web)	Download `last30days.skill` and upload via Settings > Capabilities > Skills > +
Claude Code	`/plugin marketplace add mvanhorn/last30days-skill`
OpenClaw	`clawhub install last30days-official`
Gemini CLI	Clone then `gemini extensions install ./last30days-skill` (see below)

claude.ai (web)

Download last30days.skill from the latest release
Go to claude.ai Settings > Capabilities > Skills
Click the + button in the Skills panel and drop the file in

Enable "Code execution and file creation" under Capabilities first - skills won't run without it.

Claude Code

/plugin marketplace add mvanhorn/last30days-skill

Update later with claude plugin update last30days@last30days-skill.

OpenClaw

clawhub install last30days-official

Gemini CLI

Gemini CLI v0.9.0 has an upstream installer bug that can fail with Configuration file not found at /tmp/gemini-extensionXXXXXX/gemini-extension.json (upstream issue). Workaround:

git clone https://github.com/mvanhorn/last30days-skill
gemini extensions install ./last30days-skill

Manual (developer)

git clone https://github.com/mvanhorn/last30days-skill.git ~/.claude/skills/last30days

Or build the claude.ai .skill file from source: bash scripts/build-skill.sh produces dist/last30days.skill.

Reddit (with comments), Hacker News, Polymarket, and GitHub work immediately. Zero configuration. Run /last30days once and the setup wizard unlocks more sources in 30 seconds.

Bring your own keys

These platforms don't have relationships with each other. X doesn't know what Reddit thinks. YouTube doesn't see TikTok. But you can bring your own API keys and browser tokens, and suddenly you have access to all of them at once.

Sources	What you need	Cost
Reddit (with comments) + HN + Polymarket + GitHub	Nothing	Free
X / Twitter	Log into x.com in any browser	Free
YouTube	`brew install yt-dlp`	Free
Bluesky	App password from bsky.app	Free
TikTok + Instagram + Threads + Pinterest + YouTube comments	ScrapeCreators key	10,000 free calls
Perplexity Sonar	OpenRouter key	Pay as you go
Web search	Brave Search key	2,000 free queries/month

How it works

You type a topic. Person, company, product, technology, "X vs Y." Anything.
The agent resolves who matters. Finds X handles (including founders), GitHub repos, subreddits, TikTok hashtags, YouTube channels. For "Kanye West" it knows r/hiphopheads, @kanyewest, and "bully review" on YouTube. For "OpenClaw" it resolves openclaw/openclaw on GitHub and fetches live star counts.
All sources searched in parallel. Multi-query expansion. Results scored by engagement, relevance, freshness.
The depth nobody else has. Full YouTube transcripts from reaction videos. Top Reddit comments with upvote counts. TikTok captions. Polymarket odds. Not just titles and links.
Same story, merged. Wireless Festival announced on Reddit, discussed on X, ticket prices on TikTok = one cluster, not three separate items.
Synthesized into one brief. Grounded in specific data. Cited by source. Ranked by what people actually engage with. Not "here's what I found." It's "here's what matters."
Then it becomes your expert. After one run, your Claude session knows everything the community knows. Ask follow-up questions. Have it write prompts, draft emails, plan trips, architect systems - all grounded in what's real right now.

What people are saying

"I found a Claude Code skill that researches any topic across Reddit, X, YouTube, and HN from the last 30 days. Then writes the prompts for you. I've been manually searching Reddit and X for research before every piece of content I write. Tab by tab. Thread by thread. That's the part that takes 90 minutes. This eliminates it." -@itsjasonai

"This one skill replaced my entire research workflow. You give it a topic, it scrapes Reddit, X, and the web for what people are actually talking about. Not old blog posts. Real conversations from the last 30 days." -@itswilsoncharles

"5 of the 10 trending repos on GitHub today are Claude tools. #1: mvanhorn/last30days-skill" -@yieldhunter95

Open source

MIT license. No tracking. No analytics. Your research stays on your machine. 1,012 tests.

Built with Python 3.12+, yt-dlp, Node.js (vendored Bird client for X search), and ScrapeCreators API. v3 engine architecture by @j-sperling.

See CHANGELOG.md for version history.

Star History

@slashlast30days · github.com/mvanhorn/last30days-skill

affaan-m/everything-claude-code

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

Everything Claude Code

140K+ stars | 21K+ forks | 170+ contributors | 12+ language ecosystems | Anthropic Hackathon Winner

Language / 语言 / 語言 / Dil

The performance optimization system for AI agent harnesses. From an Anthropic hackathon winner.

Not just configs. A complete system: skills, instincts, memory optimization, continuous learning, security scanning, and research-first development. Production-ready agents, skills, hooks, rules, MCP configurations, and legacy command shims evolved over 10+ months of intensive daily use building real products.

Works across Claude Code, Codex, Cursor, OpenCode, Gemini, and other AI agent harnesses.

The Guides

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


Shorthand Guide Setup, foundations, philosophy. Read this first.	Longform Guide Token optimization, memory persistence, evals, parallelization.	Security Guide Attack vectors, sandboxing, sanitization, CVEs, AgentShield.

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

What's New

v1.10.0 — Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026)

Dashboard GUI — New Tkinter-based desktop application (ecc_dashboard.py or npm run dashboard) with dark/light theme toggle, font customization, and project logo in header and taskbar.
Public surface synced to the live repo — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 38 agents, 156 skills, and 72 legacy command shims.
Operator and outbound workflow expansion — brand-voice, social-graph-ranker, connections-optimizer, customer-billing-ops, ecc-tools-cost-audit, google-workspace-ops, project-flow-ops, and workspace-surface-audit round out the operator lane.
Media and launch tooling — manim-video, remotion-video-creation, and upgraded social publishing surfaces make technical explainers and launch content part of the same system.
Framework and product surface growth — nestjs-patterns, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond Claude Code alone.
ECC 2.0 alpha is in-tree — the Rust control-plane prototype in ecc2/ now builds locally and exposes dashboard, start, sessions, status, stop, resume, and daemon commands. It is usable as an alpha, not yet a general release.
Ecosystem hardening — AgentShield, ECC Tools cost controls, billing portal work, and website refreshes continue to ship around the core plugin instead of drifting into separate silos.

v1.9.0 — Selective Install & Language Expansion (Mar 2026)

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

v1.8.0 — Harness Performance System (Mar 2026)

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

v1.7.0 — Cross-Platform Expansion & Presentation Builder (Feb 2026)

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

v1.6.0 — Codex CLI, AgentShield & Marketplace (Feb 2026)

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

v1.4.1 — Bug Fix (Feb 2026)

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

v1.4.0 — Multi-Language Rules, Installation Wizard & PM2 (Feb 2026)

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

v1.3.0 — OpenCode Plugin Support (Feb 2026)

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

v1.2.0 — Unified Commands & Skills (Feb 2026)

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

See the full changelog in Releases.

Quick Start

Get up and running in under 2 minutes:

Step 1: Install the Plugin

NOTE: The plugin is convenient, but the OSS installer below is still the most reliable path if your Claude Code build has trouble resolving self-hosted marketplace entries.

# Add marketplace
/plugin marketplace add https://github.com/affaan-m/everything-claude-code

# Install plugin
/plugin install everything-claude-code@everything-claude-code

Naming + Migration Note

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

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

This is intentional. Anthropic marketplace/plugin installs are keyed by a canonical plugin identifier, so ECC standardized on everything-claude-code@everything-claude-code to keep the listing name, /plugin install, /plugin list, and repo docs aligned to one public install surface. Older posts may still show the old short-form nickname; that shorthand is deprecated. Separately, the npm package stayed on ecc-universal, so npm installs and marketplace installs intentionally use different names.

Step 2: Install Rules (Required)

WARNING: Important: Claude Code plugins cannot distribute rules automatically. Install them manually:

If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with ecc list-installed, then run ecc doctor and ecc repair before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.

If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with ecc list-installed, then run ecc doctor and ecc repair before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.

# Clone the repo first
git clone https://github.com/affaan-m/everything-claude-code.git
cd everything-claude-code

# Install dependencies (pick your package manager)
npm install        # or: pnpm install | yarn install | bun install

# macOS/Linux

# Recommended: install everything (full profile)
./install.sh --profile full

# Or install for specific languages only
./install.sh typescript    # or python or golang or swift or php
# ./install.sh typescript python golang swift php
# ./install.sh --target cursor typescript
# ./install.sh --target antigravity typescript
# ./install.sh --target gemini --profile full

# Windows PowerShell

# Recommended: install everything (full profile)
.\install.ps1 --profile full

# Or install for specific languages only
.\install.ps1 typescript   # or python or golang or swift or php
# .\install.ps1 typescript python golang swift php
# .\install.ps1 --target cursor typescript
# .\install.ps1 --target antigravity typescript
# .\install.ps1 --target gemini --profile full

# npm-installed compatibility entrypoint also works cross-platform
npx ecc-install typescript

For manual install instructions see the README in the rules/ folder. 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.

Step 3: Start Using

# Skills are the primary workflow surface.
# Existing slash-style command names still work while ECC migrates off commands/.

# Plugin install uses the namespaced form
/ecc:plan "Add user authentication"

# Manual install keeps the shorter slash form:
# /plan "Add user authentication"

# Check available commands
/plugin list everything-claude-code@everything-claude-code

That's it! You now have access to 48 agents, 183 skills, and 79 legacy command shims.

Dashboard GUI

Launch the desktop dashboard to visually explore ECC components:

npm run dashboard
# or
python3 ./ecc_dashboard.py

Features:

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

Multi-model commands require additional setup

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

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

Initialize it with npx ccg-workflow.

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

~/.claude/bin/codeagent-wrapper

~/.claude/.ccg/prompts/*

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

Cross-Platform Support

This plugin now fully supports Windows, macOS, and Linux, alongside tight integration across major IDEs (Cursor, OpenCode, Antigravity) and CLI harnesses. All hooks and scripts have been rewritten in Node.js for maximum compatibility.

Package Manager Detection

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

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

To set your preferred package manager:

# Via environment variable
export CLAUDE_PACKAGE_MANAGER=pnpm

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

# Via project config
node scripts/setup-package-manager.js --project bun

# Detect current setting
node scripts/setup-package-manager.js --detect

Or use the /setup-pm command in Claude Code.

Hook Runtime Controls

Use runtime flags to tune strictness or disable specific hooks temporarily:

# Hook strictness profile (default: standard)
export ECC_HOOK_PROFILE=standard

# Comma-separated hook IDs to disable
export ECC_DISABLED_HOOKS="pre:bash:tmux-reminder,post:edit:typecheck"

What's Inside

This repo is a Claude Code plugin - install it directly or copy components manually.

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

Ecosystem Tools

Skill Creator

Two ways to generate Claude Code skills from your repository:

Option A: Local Analysis (Built-in)

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

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

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

Option B: GitHub App (Advanced)

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

Install GitHub App | ecc.tools

# Comment on any issue:
/skill-creator analyze

# Or auto-triggers on push to default branch

Both options create:

SKILL.md files - Ready-to-use skills for Claude Code
Instinct collections - For continuous-learning-v2
Pattern extraction - Learns from your commit history

AgentShield — Security Auditor

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

Scan your Claude Code configuration for vulnerabilities, misconfigurations, and injection risks.

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

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

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

# Generate secure config from scratch
npx ecc-agentshield init

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

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

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

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

GitHub | npm

Continuous Learning v2

The instinct-based learning system automatically learns your patterns:

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

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

Requirements

Claude Code CLI Version

Minimum version: v2.1.0 or later

This plugin requires Claude Code CLI v2.1.0+ due to changes in how the plugin system handles hooks.

Check your version:

claude --version

Important: Hooks Auto-Loading Behavior

WARNING: For Contributors: Do NOT add a "hooks" field to .claude-plugin/plugin.json. This is enforced by a regression test.

Claude Code v2.1+ automatically loads hooks/hooks.json from any installed plugin by convention. Explicitly declaring it in plugin.json causes a duplicate detection error:

Duplicate hooks file detected: ./hooks/hooks.json resolves to already-loaded file

History: This has caused repeated fix/revert cycles in this repo (#29, #52, #103). The behavior changed between Claude Code versions, leading to confusion. We now have a regression test to prevent this from being reintroduced.

Installation

Option 1: Install as Plugin (Recommended)

The easiest way to use this repo - install as a Claude Code plugin:

# Add this repo as a marketplace
/plugin marketplace add https://github.com/affaan-m/everything-claude-code

# Install the plugin
/plugin install everything-claude-code@everything-claude-code

Or add directly to your ~/.claude/settings.json:

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

This gives you instant access to all commands, agents, skills, and hooks.

Note: The Claude Code plugin system does not support distributing rules via plugins (upstream limitation). You need to install rules manually:

# Clone the repo first
git clone https://github.com/affaan-m/everything-claude-code.git

# Option A: User-level rules (applies to all projects)
mkdir -p ~/.claude/rules
cp -r everything-claude-code/rules/common ~/.claude/rules/
cp -r everything-claude-code/rules/typescript ~/.claude/rules/   # pick your stack
cp -r everything-claude-code/rules/python ~/.claude/rules/
cp -r everything-claude-code/rules/golang ~/.claude/rules/
cp -r everything-claude-code/rules/php ~/.claude/rules/

# Option B: Project-level rules (applies to current project only)
mkdir -p .claude/rules
cp -r everything-claude-code/rules/common .claude/rules/
cp -r everything-claude-code/rules/typescript .claude/rules/     # pick your stack

Option 2: Manual Installation

If you prefer manual control over what's installed:

# Clone the repo
git clone https://github.com/affaan-m/everything-claude-code.git

# Copy agents to your Claude config
cp everything-claude-code/agents/*.md ~/.claude/agents/

# Copy rules directories (common + language-specific)
mkdir -p ~/.claude/rules
cp -r everything-claude-code/rules/common ~/.claude/rules/
cp -r everything-claude-code/rules/typescript ~/.claude/rules/   # pick your stack
cp -r everything-claude-code/rules/python ~/.claude/rules/
cp -r everything-claude-code/rules/golang ~/.claude/rules/
cp -r everything-claude-code/rules/php ~/.claude/rules/

# Copy skills first (primary workflow surface)
# Recommended (new users): core/general skills only
cp -r everything-claude-code/.agents/skills/* ~/.claude/skills/
cp -r everything-claude-code/skills/search-first ~/.claude/skills/

# Optional: add niche/framework-specific skills only when needed
# for s in django-patterns django-tdd laravel-patterns springboot-patterns; do
# cp -r everything-claude-code/skills/$s ~/.claude/skills/
# done

# Optional: keep legacy slash-command compatibility during migration
mkdir -p ~/.claude/commands
cp everything-claude-code/commands/*.md ~/.claude/commands/

Install hooks

Do not copy the raw repo hooks/hooks.json into ~/.claude/settings.json or ~/.claude/hooks/hooks.json. That file is plugin/repo-oriented and is meant to be installed through the ECC installer or loaded as a plugin, so raw copying is not a supported manual install path.

Use the installer to install only the Claude hook runtime so command paths are rewritten correctly:

# macOS / Linux
bash ./install.sh --target claude --modules hooks-runtime

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

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

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

Windows note: the Claude config directory is %USERPROFILE%\\.claude, not ~/claude.

Configure MCPs

Copy desired MCP server definitions from mcp-configs/mcp-servers.json into your official Claude Code config in ~/.claude/settings.json, or into a project-scoped .mcp.json if you want repo-local MCP access.

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

export ECC_DISABLED_MCPS="github,context7,exa,playwright,sequential-thinking,memory"

ECC-managed install and Codex sync flows will skip or remove those bundled servers instead of re-adding duplicates.

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

Key Concepts

Agents

Subagents handle delegated tasks with limited scope. Example:

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

You are a senior code reviewer...

Skills

Skills are the primary workflow surface. They can be invoked directly, suggested automatically, and reused by agents. ECC still ships commands/ during migration, but new workflow development should land in skills/ first.

# TDD Workflow

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

Hooks

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

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

Rules

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

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

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

Which Agent Should I Use?

Not sure where to start? Use this quick reference. Skills are the canonical workflow surface; slash entries below are the compatibility form most users already know.

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

Common Workflows

Slash forms below are shown because they are still the fastest familiar entrypoint. Under the hood, ECC is shifting these workflows toward skills-first definitions.

Starting a new feature:

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

Fixing a bug:

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

Preparing for production:

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

FAQ

How do I check which agents/commands are installed?

/plugin list everything-claude-code@everything-claude-code

This shows all available agents, commands, and skills from the plugin.

My hooks aren't working / I see "Duplicate hooks file" errors

This is the most common issue. Do NOT add a "hooks" field to .claude-plugin/plugin.json. Claude Code v2.1+ automatically loads hooks/hooks.json from installed plugins. Explicitly declaring it causes duplicate detection errors. See #29, #52, #103.

Can I use ECC with Claude Code on a custom API endpoint or model gateway?

Yes. ECC does not hardcode Anthropic-hosted transport settings. It runs locally through Claude Code's normal CLI/plugin surface, so it works with:

Anthropic-hosted Claude Code
Official Claude Code gateway setups using ANTHROPIC_BASE_URL and ANTHROPIC_AUTH_TOKEN
Compatible custom endpoints that speak the Anthropic API Claude Code expects

Minimal example:

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

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

Official references:

My context window is shrinking / Claude is running out of context

Too many MCP servers eat your context. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.

Fix: Disable unused MCPs per project:

// In your project's .claude/settings.json
{
  "disabledMcpServers": ["supabase", "railway", "vercel"]
}

Keep under 10 MCPs enabled and under 80 tools active.

Can I use only some components (e.g., just agents)?

Yes. Use Option 2 (manual installation) and copy only what you need:

# Just agents
cp everything-claude-code/agents/*.md ~/.claude/agents/

# Just rules
mkdir -p ~/.claude/rules/
cp -r everything-claude-code/rules/common ~/.claude/rules/

Each component is fully independent.

Does this work with Cursor / OpenCode / Codex / Antigravity?

Yes. ECC is cross-platform:

Cursor: Pre-translated configs in .cursor/. See Cursor IDE Support.
Gemini CLI: Experimental project-local support via .gemini/GEMINI.md and shared installer plumbing.
OpenCode: Full plugin support in .opencode/. See OpenCode Support.
Codex: First-class support for both macOS app and CLI, with adapter drift guards and SessionStart fallback. See PR #257.
Antigravity: Tightly integrated setup for workflows, skills, and flattened rules in .agent/. See Antigravity Guide.
Non-native harnesses: Manual fallback path for Grok and similar interfaces. See Manual Adaptation Guide.
Claude Code: Native — this is the primary target.

How do I contribute a new skill or agent?

See CONTRIBUTING.md. The short version:

Fork the repo
Create your skill in skills/your-skill-name/SKILL.md (with YAML frontmatter)
Or create an agent in agents/your-agent.md
Submit a PR with a clear description of what it does and when to use it

Running Tests

The plugin includes a comprehensive test suite:

# Run all tests
node tests/run-all.js

# Run individual test files
node tests/lib/utils.test.js
node tests/lib/package-manager.test.js
node tests/hooks/hooks.test.js

Contributing

Contributions are welcome and encouraged.

This repo is meant to be a community resource. If you have:

Useful agents or skills
Clever hooks
Better MCP configurations
Improved rules

Please contribute! See CONTRIBUTING.md for guidelines.

Ideas for Contributions

Language-specific skills (Rust, C#, Kotlin, Java) — Go, Python, Perl, Swift, and TypeScript already included
Framework-specific configs (Rails, FastAPI) — Django, NestJS, Spring Boot, and Laravel already included
DevOps agents (Kubernetes, Terraform, AWS, Docker)
Testing strategies (different frameworks, visual regression)
Domain-specific knowledge (ML, data engineering, mobile)

Community Ecosystem Notes

These are not bundled with ECC and are not audited by this repo, but they are worth knowing about if you are exploring the broader Claude Code skills ecosystem:

claude-seo — SEO-focused skill and agent collection
claude-ads — Ad-audit and paid-growth workflow collection
claude-cybersecurity — Security-oriented skill and agent collection

Cursor IDE Support

ECC provides full Cursor IDE support with hooks, rules, agents, skills, commands, and MCP configs adapted for Cursor's native format.

Quick Start (Cursor)

# macOS/Linux
./install.sh --target cursor typescript
./install.sh --target cursor python golang swift php

# Windows PowerShell
.\install.ps1 --target cursor typescript
.\install.ps1 --target cursor python golang swift php

What's Included

Component	Count	Details
Hook Events	15	sessionStart, beforeShellExecution, afterFileEdit, beforeMCPExecution, beforeSubmitPrompt, and 10 more
Hook Scripts	16	Thin Node.js scripts delegating to `scripts/hooks/` via shared adapter
Rules	34	9 common (alwaysApply) + 25 language-specific (TypeScript, Python, Go, Swift, PHP)
Agents	Shared	Via AGENTS.md at root (read by Cursor natively)
Skills	Shared + Bundled	Via AGENTS.md at root and `.cursor/skills/` for translated additions
Commands	Shared	`.cursor/commands/` if installed
MCP Config	Shared	`.cursor/mcp.json` if installed

Hook Architecture (DRY Adapter Pattern)

Cursor has more hook events than Claude Code (20 vs 8). The .cursor/hooks/adapter.js module transforms Cursor's stdin JSON to Claude Code's format, allowing existing scripts/hooks/*.js to be reused without duplication.

Cursor stdin JSON → adapter.js → transforms → scripts/hooks/*.js
                                              (shared with Claude Code)

Key hooks:

beforeShellExecution — Blocks dev servers outside tmux (exit 2), git push review
afterFileEdit — Auto-format + TypeScript check + console.log warning
beforeSubmitPrompt — Detects secrets (sk-, ghp_, AKIA patterns) in prompts
beforeTabFileRead — Blocks Tab from reading .env, .key, .pem files (exit 2)
beforeMCPExecution / afterMCPExecution — MCP audit logging

Rules Format

Cursor rules use YAML frontmatter with description, globs, and alwaysApply:

---
description: "TypeScript coding style extending common rules"
globs: ["**/*.ts", "**/*.tsx", "**/*.js", "**/*.jsx"]
alwaysApply: false
---

Codex macOS App + CLI Support

ECC provides first-class Codex support for both the macOS app and CLI, with a reference configuration, Codex-specific AGENTS.md supplement, and shared skills.

Quick Start (Codex App + CLI)

# Run Codex CLI in the repo — AGENTS.md and .codex/ are auto-detected
codex

# Automatic setup: sync ECC assets (AGENTS.md, skills, MCP servers) into ~/.codex
npm install && bash scripts/sync-ecc-to-codex.sh
# or: pnpm install && bash scripts/sync-ecc-to-codex.sh
# or: yarn install && bash scripts/sync-ecc-to-codex.sh
# or: bun install && bash scripts/sync-ecc-to-codex.sh

# Or manually: copy the reference config to your home directory
cp .codex/config.toml ~/.codex/config.toml

The sync script safely merges ECC MCP servers into your existing ~/.codex/config.toml using an add-only strategy — it never removes or modifies your existing servers. Run with --dry-run to preview changes, or --update-mcp to force-refresh ECC servers to the latest recommended config.

For Context7, ECC uses the canonical Codex section name [mcp_servers.context7] while still launching the @upstash/context7-mcp package. If you already have a legacy [mcp_servers.context7-mcp] entry, --update-mcp migrates it to the canonical section name.

Codex macOS app:

Open this repository as your workspace.
The root AGENTS.md is auto-detected.
.codex/config.toml and .codex/agents/*.toml work best when kept project-local.
The reference .codex/config.toml intentionally does not pin model or model_provider, so Codex uses its own current default unless you override it.
Optional: copy .codex/config.toml to ~/.codex/config.toml for global defaults; keep the multi-agent role files project-local unless you also copy .codex/agents/.

What's Included

Component	Count	Details
Config	1	`.codex/config.toml` — top-level approvals/sandbox/web_search, MCP servers, notifications, profiles
AGENTS.md	2	Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement)
Skills	30	`.agents/skills/` — SKILL.md + agents/openai.yaml per skill
MCP Servers	6	GitHub, Context7, Exa, Memory, Playwright, Sequential Thinking (7 with Supabase via `--update-mcp` sync)
Profiles	2	`strict` (read-only sandbox) and `yolo` (full auto-approve)
Agent Roles	3	`.codex/agents/` — explorer, reviewer, docs-researcher

Skills

Skills at .agents/skills/ are auto-loaded by Codex:

Skill	Description
api-design	REST API design patterns
article-writing	Long-form writing from notes and voice references
backend-patterns	API design, database, caching
brand-voice	Source-derived writing style profiles from real content
bun-runtime	Bun as runtime, package manager, bundler, and test runner
claude-api	Anthropic Claude API patterns for Python and TypeScript
coding-standards	Universal coding standards
content-engine	Platform-native social content and repurposing
crosspost	Multi-platform content distribution across X, LinkedIn, Threads
deep-research	Multi-source research with synthesis and source attribution
dmux-workflows	Multi-agent orchestration using tmux pane manager
documentation-lookup	Up-to-date library and framework docs via Context7 MCP
e2e-testing	Playwright E2E tests
eval-harness	Eval-driven development
everything-claude-code	Development conventions and patterns for the project
exa-search	Neural search via Exa MCP for web, code, company research
fal-ai-media	Unified media generation for images, video, and audio
frontend-patterns	React/Next.js patterns
frontend-slides	HTML presentations, PPTX conversion, visual style exploration
investor-materials	Decks, memos, models, and one-pagers
investor-outreach	Personalized outreach, follow-ups, and intro blurbs
market-research	Source-attributed market and competitor research
mcp-server-patterns	Build MCP servers with Node/TypeScript SDK
nextjs-turbopack	Next.js 16+ and Turbopack incremental bundling
security-review	Comprehensive security checklist
strategic-compact	Context management
tdd-workflow	Test-driven development with 80%+ coverage
verification-loop	Build, test, lint, typecheck, security
video-editing	AI-assisted video editing workflows with FFmpeg and Remotion
x-api	X/Twitter API integration for posting and analytics

Key Limitation

Codex does not yet provide Claude-style hook execution parity. ECC enforcement there is instruction-based via AGENTS.md, optional model_instructions_file overrides, and sandbox/approval settings.

Multi-Agent Support

Current Codex builds support stable multi-agent workflows.

Enable features.multi_agent = true in .codex/config.toml
Define roles under [agents.<name>]
Point each role at a file under .codex/agents/
Use /agent in the CLI to inspect or steer child agents

ECC ships three sample role configs:

Role	Purpose
`explorer`	Read-only codebase evidence gathering before edits
`reviewer`	Correctness, security, and missing-test review
`docs_researcher`	Documentation and API verification before release/docs changes

OpenCode Support

ECC provides full OpenCode support including plugins and hooks.

Quick Start

# Install OpenCode
npm install -g opencode

# Run in the repository root
opencode

The configuration is automatically detected from .opencode/opencode.json.

Feature Parity

Feature	Claude Code	OpenCode	Status
Agents	PASS: 48 agents	PASS: 12 agents	Claude Code leads
Commands	PASS: 79 commands	PASS: 31 commands	Claude Code leads
Skills	PASS: 183 skills	PASS: 37 skills	Claude Code leads
Hooks	PASS: 8 event types	PASS: 11 events	OpenCode has more!
Rules	PASS: 29 rules	PASS: 13 instructions	Claude Code leads
MCP Servers	PASS: 14 servers	PASS: Full	Full parity
Custom Tools	PASS: Via hooks	PASS: 6 native tools	OpenCode is better

Hook Support via Plugins

OpenCode's plugin system is MORE sophisticated than Claude Code with 20+ event types:

Claude Code Hook	OpenCode Plugin Event
PreToolUse	`tool.execute.before`
PostToolUse	`tool.execute.after`
Stop	`session.idle`
SessionStart	`session.created`
SessionEnd	`session.deleted`

Additional OpenCode events: file.edited, file.watcher.updated, message.updated, lsp.client.diagnostics, tui.toast.show, and more.

Available Slash Entry Shims (31+)

Command	Description
`/plan`	Create implementation plan
`/tdd`	Enforce TDD workflow
`/code-review`	Review code changes
`/build-fix`	Fix build errors
`/e2e`	Generate E2E tests
`/refactor-clean`	Remove dead code
`/orchestrate`	Multi-agent workflow
`/learn`	Extract patterns from session
`/checkpoint`	Save verification state
`/verify`	Run verification loop
`/eval`	Evaluate against criteria
`/update-docs`	Update documentation
`/update-codemaps`	Update codemaps
`/test-coverage`	Analyze coverage
`/go-review`	Go code review
`/go-test`	Go TDD workflow
`/go-build`	Fix Go build errors
`/python-review`	Python code review (PEP 8, type hints, security)
`/multi-plan`	Multi-model collaborative planning
`/multi-execute`	Multi-model collaborative execution
`/multi-backend`	Backend-focused multi-model workflow
`/multi-frontend`	Frontend-focused multi-model workflow
`/multi-workflow`	Full multi-model development workflow
`/pm2`	Auto-generate PM2 service commands
`/sessions`	Manage session history
`/skill-create`	Generate skills from git
`/instinct-status`	View learned instincts
`/instinct-import`	Import instincts
`/instinct-export`	Export instincts
`/evolve`	Cluster instincts into skills
`/promote`	Promote project instincts to global scope
`/projects`	List known projects and instinct stats
`/prune`	Delete expired pending instincts (30d TTL)
`/learn-eval`	Extract and evaluate patterns before saving
`/setup-pm`	Configure package manager
`/harness-audit`	Audit harness reliability, eval readiness, and risk posture
`/loop-start`	Start controlled agentic loop execution pattern
`/loop-status`	Inspect active loop status and checkpoints
`/quality-gate`	Run quality gate checks for paths or entire repo
`/model-route`	Route tasks to models by complexity and budget

Plugin Installation

Option 1: Use directly

cd everything-claude-code
opencode

Option 2: Install as npm package

npm install ecc-universal

Then add to your opencode.json:

{
  "plugin": ["ecc-universal"]
}

That npm plugin entry enables ECC's published OpenCode plugin module (hooks/events and plugin tools). It does not automatically add ECC's full command/agent/instruction catalog to your project config.

For the full ECC OpenCode setup, either:

run OpenCode inside this repository, or
copy the bundled .opencode/ config assets into your project and wire the instructions, agent, and command entries in opencode.json

Documentation

Migration Guide: .opencode/MIGRATION.md
OpenCode Plugin README: .opencode/README.md
Consolidated Rules: .opencode/instructions/INSTRUCTIONS.md
LLM Documentation: llms.txt (complete OpenCode docs for LLMs)

Cross-Tool Feature Parity

ECC is the first plugin to maximize every major AI coding tool. Here's how each harness compares:

Feature	Claude Code	Cursor IDE	Codex CLI	OpenCode
Agents	48	Shared (AGENTS.md)	Shared (AGENTS.md)	12
Commands	79	Shared	Instruction-based	31
Skills	183	Shared	10 (native format)	37
Hook Events	8 types	15 types	None yet	11 types
Hook Scripts	20+ scripts	16 scripts (DRY adapter)	N/A	Plugin hooks
Rules	34 (common + lang)	34 (YAML frontmatter)	Instruction-based	13 instructions
Custom Tools	Via hooks	Via hooks	N/A	6 native tools
MCP Servers	14	Shared (mcp.json)	7 (auto-merged via TOML parser)	Full
Config Format	settings.json	hooks.json + rules/	config.toml	opencode.json
Context File	CLAUDE.md + AGENTS.md	AGENTS.md	AGENTS.md	AGENTS.md
Secret Detection	Hook-based	beforeSubmitPrompt hook	Sandbox-based	Hook-based
Auto-Format	PostToolUse hook	afterFileEdit hook	N/A	file.edited hook
Version	Plugin	Plugin	Reference config	1.10.0

Key architectural decisions:

AGENTS.md at root is the universal cross-tool file (read by all 4 tools)
DRY adapter pattern lets Cursor reuse Claude Code's hook scripts without duplication
Skills format (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
Codex's lack of hooks is compensated by AGENTS.md, optional model_instructions_file overrides, and sandbox permissions

Background

I've been using Claude Code since the experimental rollout. Won the Anthropic x Forum Ventures hackathon in Sep 2025 with @DRodriguezFX — built zenith.chat entirely using Claude Code.

These configs are battle-tested across multiple production applications.

Token Optimization

Claude Code usage can be expensive if you don't manage token consumption. These settings significantly reduce costs without sacrificing quality.

Recommended Settings

Add to ~/.claude/settings.json:

{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50"
  }
}

Setting	Default	Recommended	Impact
`model`	opus	sonnet	~60% cost reduction; handles 80%+ of coding tasks
`MAX_THINKING_TOKENS`	31,999	10,000	~70% reduction in hidden thinking cost per request
`CLAUDE_AUTOCOMPACT_PCT_OVERRIDE`	95	50	Compacts earlier — better quality in long sessions

Switch to Opus only when you need deep architectural reasoning:

/model opus

Daily Workflow Commands

Command	When to Use
`/model sonnet`	Default for most tasks
`/model opus`	Complex architecture, debugging, deep reasoning
`/clear`	Between unrelated tasks (free, instant reset)
`/compact`	At logical task breakpoints (research done, milestone complete)
`/cost`	Monitor token spending during session

Strategic Compaction

The strategic-compact skill (included in this plugin) suggests /compact at logical breakpoints instead of relying on auto-compaction at 95% context. See skills/strategic-compact/SKILL.md for the full decision guide.

When to compact:

After research/exploration, before implementation
After completing a milestone, before starting the next
After debugging, before continuing feature work
After a failed approach, before trying a new one

When NOT to compact:

Mid-implementation (you'll lose variable names, file paths, partial state)

Context Window Management

Critical: Don't enable all MCPs at once. Each MCP tool description consumes tokens from your 200k window, potentially reducing it to ~70k.

Keep under 10 MCPs enabled per project
Keep under 80 tools active
Use disabledMcpServers in project config to disable unused ones

Agent Teams Cost Warning

Agent Teams spawns multiple context windows. Each teammate consumes tokens independently. Only use for tasks where parallelism provides clear value (multi-module work, parallel reviews). For simple sequential tasks, subagents are more token-efficient.

WARNING: Important Notes

Token Optimization

Hitting daily limits? See the Token Optimization Guide for recommended settings and workflow tips.

Quick wins:

// ~/.claude/settings.json
{
  "model": "sonnet",
  "env": {
    "MAX_THINKING_TOKENS": "10000",
    "CLAUDE_AUTOCOMPACT_PCT_OVERRIDE": "50",
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku"
  }
}

Use /clear between unrelated tasks, /compact at logical breakpoints, and /cost to monitor spending.

Customization

These configs work for my workflow. You should:

Start with what resonates
Modify for your stack
Remove what you don't use
Add your own patterns

Community Projects

Projects built on or inspired by Everything Claude Code:

Project	Description
EVC	Marketing agent workspace — 42 commands for content operators, brand governance, and multi-channel publishing. Visual overview.

Built something with ECC? Open a PR to add it here.

Star History

License

MIT - Use freely, modify as needed, contribute back if you can.

Star this repo if it helps. Read both guides. Build something great.

microsoft/markitdown

Python tool for converting files and office documents to Markdown.

MarkItDown

Tip

MarkItDown now offers an MCP (Model Context Protocol) server for integration with LLM applications like Claude Desktop. See markitdown-mcp for more information.

Important

Breaking changes between 0.0.1 to 0.1.0:

Dependencies are now organized into optional feature-groups (further details below). Use pip install 'markitdown[all]' to have backward-compatible behavior.
convert_stream() now requires a binary file-like object (e.g., a file opened in binary mode, or an io.BytesIO object). This is a breaking change from the previous version, where it previously also accepted text file-like objects, like io.StringIO.
The DocumentConverter class interface has changed to read from file-like streams rather than file paths. No temporary files are created anymore. If you are the maintainer of a plugin, or custom DocumentConverter, you likely need to update your code. Otherwise, if only using the MarkItDown class or CLI (as in these examples), you should not need to change anything.

MarkItDown is a lightweight Python utility for converting various files to Markdown for use with LLMs and related text analysis pipelines. To this end, it is most comparable to textract, but with a focus on preserving important document structure and content as Markdown (including: headings, lists, tables, links, etc.) While the output is often reasonably presentable and human-friendly, it is meant to be consumed by text analysis tools -- and may not be the best option for high-fidelity document conversions for human consumption.

MarkItDown currently supports the conversion from:

PDF
PowerPoint
Word
Excel
Images (EXIF metadata and OCR)
Audio (EXIF metadata and speech transcription)
HTML
Text-based formats (CSV, JSON, XML)
ZIP files (iterates over contents)
Youtube URLs
EPubs
... and more!

Why Markdown?

Markdown is extremely close to plain text, with minimal markup or formatting, but still provides a way to represent important document structure. Mainstream LLMs, such as OpenAI's GPT-4o, natively "speak" Markdown, and often incorporate Markdown into their responses unprompted. This suggests that they have been trained on vast amounts of Markdown-formatted text, and understand it well. As a side benefit, Markdown conventions are also highly token-efficient.

Prerequisites

MarkItDown requires Python 3.10 or higher. It is recommended to use a virtual environment to avoid dependency conflicts.

With the standard Python installation, you can create and activate a virtual environment using the following commands:

python -m venv .venv
source .venv/bin/activate

If using uv, you can create a virtual environment with:

uv venv --python=3.12 .venv
source .venv/bin/activate
# NOTE: Be sure to use 'uv pip install' rather than just 'pip install' to install packages in this virtual environment

If you are using Anaconda, you can create a virtual environment with:

conda create -n markitdown python=3.12
conda activate markitdown

Installation

To install MarkItDown, use pip: pip install 'markitdown[all]'. Alternatively, you can install it from the source:

git clone git@github.com:microsoft/markitdown.git
cd markitdown
pip install -e 'packages/markitdown[all]'

Usage

Command-Line

markitdown path-to-file.pdf > document.md

Or use -o to specify the output file:

markitdown path-to-file.pdf -o document.md

You can also pipe content:

cat path-to-file.pdf | markitdown

Optional Dependencies

MarkItDown has optional dependencies for activating various file formats. Earlier in this document, we installed all optional dependencies with the [all] option. However, you can also install them individually for more control. For example:

pip install 'markitdown[pdf, docx, pptx]'

will install only the dependencies for PDF, DOCX, and PPTX files.

At the moment, the following optional dependencies are available:

[all] Installs all optional dependencies
[pptx] Installs dependencies for PowerPoint files
[docx] Installs dependencies for Word files
[xlsx] Installs dependencies for Excel files
[xls] Installs dependencies for older Excel files
[pdf] Installs dependencies for PDF files
[outlook] Installs dependencies for Outlook messages
[az-doc-intel] Installs dependencies for Azure Document Intelligence
[audio-transcription] Installs dependencies for audio transcription of wav and mp3 files
[youtube-transcription] Installs dependencies for fetching YouTube video transcription

Plugins

MarkItDown also supports 3rd-party plugins. Plugins are disabled by default. To list installed plugins:

markitdown --list-plugins

To enable plugins use:

markitdown --use-plugins path-to-file.pdf

To find available plugins, search GitHub for the hashtag #markitdown-plugin. To develop a plugin, see packages/markitdown-sample-plugin.

markitdown-ocr Plugin

The markitdown-ocr plugin adds OCR support to PDF, DOCX, PPTX, and XLSX converters, extracting text from embedded images using LLM Vision — the same llm_client / llm_model pattern that MarkItDown already uses for image descriptions. No new ML libraries or binary dependencies required.

Installation:

pip install markitdown-ocr
pip install openai  # or any OpenAI-compatible client

Usage:

Pass the same llm_client and llm_model you would use for image descriptions:

from markitdown import MarkItDown
from openai import OpenAI

md = MarkItDown(
    enable_plugins=True,
    llm_client=OpenAI(),
    llm_model="gpt-4o",
)
result = md.convert("document_with_images.pdf")
print(result.text_content)

If no llm_client is provided the plugin still loads, but OCR is silently skipped and the standard built-in converter is used instead.

See packages/markitdown-ocr/README.md for detailed documentation.

Azure Document Intelligence

To use Microsoft Document Intelligence for conversion:

markitdown path-to-file.pdf -o document.md -d -e "<document_intelligence_endpoint>"

More information about how to set up an Azure Document Intelligence Resource can be found here

Python API

Basic usage in Python:

from markitdown import MarkItDown

md = MarkItDown(enable_plugins=False) # Set to True to enable plugins
result = md.convert("test.xlsx")
print(result.text_content)

Document Intelligence conversion in Python:

from markitdown import MarkItDown

md = MarkItDown(docintel_endpoint="<document_intelligence_endpoint>")
result = md.convert("test.pdf")
print(result.text_content)

To use Large Language Models for image descriptions (currently only for pptx and image files), provide llm_client and llm_model:

from markitdown import MarkItDown
from openai import OpenAI

client = OpenAI()
md = MarkItDown(llm_client=client, llm_model="gpt-4o", llm_prompt="optional custom prompt")
result = md.convert("example.jpg")
print(result.text_content)

Docker

docker build -t markitdown:latest .
docker run --rm -i markitdown:latest < ~/your-file.pdf > output.md

Contributing

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

How to Contribute

You can help by looking at issues or helping review PRs. Any issue or PR is welcome, but we have also marked some as 'open for contribution' and 'open for reviewing' to help facilitate community contributions. These are of course just suggestions and you are welcome to contribute in any way you like.

	All	Especially Needs Help from Community
Issues	All Issues	Issues open for contribution
PRs	All PRs	PRs open for reviewing

Running Tests and Checks

Navigate to the MarkItDown package:
```
cd packages/markitdown
```

Install hatch in your environment and run tests:

pip install hatch  # Other ways of installing hatch: https://hatch.pypa.io/dev/install/
hatch shell
hatch test

(Alternative) Use the Devcontainer which has all the dependencies installed:

# Reopen the project in Devcontainer and run:
hatch test

Run pre-commit checks before submitting a PR: pre-commit run --all-files

Contributing 3rd-party Plugins

You can also contribute by creating and sharing 3rd party plugins. See packages/markitdown-sample-plugin for more details.

Trademarks

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.

shiyu-coder/Kronos

Kronos: A Foundation Model for the Language of Financial Markets

Kronos is the first open-source foundation model for financial candlesticks (K-lines), trained on data from over 45 global exchanges.

📰 News

🚩 [2025.11.10] Kronos has been accpeted by AAAI 2026.
🚩 [2025.08.17] We have released the scripts for fine-tuning! Check them out to adapt Kronos to your own tasks.
🚩 [2025.08.02] Our paper is now available on arXiv!

📜 Introduction

Kronos is a family of decoder-only foundation models, pre-trained specifically for the "language" of financial markets—K-line sequences. Unlike general-purpose TSFMs, Kronos is designed to handle the unique, high-noise characteristics of financial data. It leverages a novel two-stage framework:

A specialized tokenizer first quantizes continuous, multi-dimensional K-line data (OHLCV) into hierarchical discrete tokens.
A large, autoregressive Transformer is then pre-trained on these tokens, enabling it to serve as a unified model for diverse quantitative tasks.

✨ Live Demo

We have set up a live demo to visualize Kronos's forecasting results. The webpage showcases a forecast for the BTC/USDT trading pair over the next 24 hours.

👉 Access the Live Demo Here

📦 Model Zoo

We release a family of pre-trained models with varying capacities to suit different computational and application needs. All models are readily accessible from the Hugging Face Hub.

Model	Tokenizer	Context length	Params	Open-source
Kronos-mini	Kronos-Tokenizer-2k	2048	4.1M	✅ NeoQuasar/Kronos-mini
Kronos-small	Kronos-Tokenizer-base	512	24.7M	✅ NeoQuasar/Kronos-small
Kronos-base	Kronos-Tokenizer-base	512	102.3M	✅ NeoQuasar/Kronos-base
Kronos-large	Kronos-Tokenizer-base	512	499.2M	❌

🚀 Getting Started

Installation

Install Python 3.10+, and then install the dependencies:

pip install -r requirements.txt

📈 Making Forecasts

Forecasting with Kronos is straightforward using the KronosPredictor class. It handles data preprocessing, normalization, prediction, and inverse normalization, allowing you to get from raw data to forecasts in just a few lines of code.

Important Note: The max_context for Kronos-small and Kronos-base is 512. This is the maximum sequence length the model can process. For optimal performance, it is recommended that your input data length (i.e., lookback) does not exceed this limit. The KronosPredictor will automatically handle truncation for longer contexts.

Here is a step-by-step guide to making your first forecast.

1. Load the Tokenizer and Model

First, load a pre-trained Kronos model and its corresponding tokenizer from the Hugging Face Hub.

from model import Kronos, KronosTokenizer, KronosPredictor

# Load from Hugging Face Hub
tokenizer = KronosTokenizer.from_pretrained("NeoQuasar/Kronos-Tokenizer-base")
model = Kronos.from_pretrained("NeoQuasar/Kronos-small")

2. Instantiate the Predictor

Create an instance of KronosPredictor, passing the model, tokenizer, and desired device.

# Initialize the predictor
predictor = KronosPredictor(model, tokenizer, max_context=512)

3. Prepare Input Data

The predict method requires three main inputs:

df: A pandas DataFrame containing the historical K-line data. It must include columns ['open', 'high', 'low', 'close']. volume and amount are optional.
x_timestamp: A pandas Series of timestamps corresponding to the historical data in df.
y_timestamp: A pandas Series of timestamps for the future periods you want to predict.

import pandas as pd

# Load your data
df = pd.read_csv("./data/XSHG_5min_600977.csv")
df['timestamps'] = pd.to_datetime(df['timestamps'])

# Define context window and prediction length
lookback = 400
pred_len = 120

# Prepare inputs for the predictor
x_df = df.loc[:lookback-1, ['open', 'high', 'low', 'close', 'volume', 'amount']]
x_timestamp = df.loc[:lookback-1, 'timestamps']
y_timestamp = df.loc[lookback:lookback+pred_len-1, 'timestamps']

4. Generate Forecasts

Call the predict method to generate forecasts. You can control the sampling process with parameters like T, top_p, and sample_count for probabilistic forecasting.

# Generate predictions
pred_df = predictor.predict(
    df=x_df,
    x_timestamp=x_timestamp,
    y_timestamp=y_timestamp,
    pred_len=pred_len,
    T=1.0,          # Temperature for sampling
    top_p=0.9,      # Nucleus sampling probability
    sample_count=1  # Number of forecast paths to generate and average
)

print("Forecasted Data Head:")
print(pred_df.head())

The predict method returns a pandas DataFrame containing the forecasted values for open, high, low, close, volume, and amount, indexed by the y_timestamp you provided.

For efficient processing of multiple time series, Kronos provides a predict_batch method that enables parallel prediction on multiple datasets simultaneously. This is particularly useful when you need to forecast multiple assets or time periods at once.

# Prepare multiple datasets for batch prediction
df_list = [df1, df2, df3]  # List of DataFrames
x_timestamp_list = [x_ts1, x_ts2, x_ts3]  # List of historical timestamps
y_timestamp_list = [y_ts1, y_ts2, y_ts3]  # List of future timestamps

# Generate batch predictions
pred_df_list = predictor.predict_batch(
    df_list=df_list,
    x_timestamp_list=x_timestamp_list,
    y_timestamp_list=y_timestamp_list,
    pred_len=pred_len,
    T=1.0,
    top_p=0.9,
    sample_count=1,
    verbose=True
)

# pred_df_list contains prediction results in the same order as input
for i, pred_df in enumerate(pred_df_list):
    print(f"Predictions for series {i}:")
    print(pred_df.head())

Important Requirements for Batch Prediction:

All series must have the same historical length (lookback window)
All series must have the same prediction length (pred_len)
Each DataFrame must contain the required columns: ['open', 'high', 'low', 'close']
volume and amount columns are optional and will be filled with zeros if missing

The predict_batch method leverages GPU parallelism for efficient processing and automatically handles normalization and denormalization for each series independently.

5. Example and Visualization

For a complete, runnable script that includes data loading, prediction, and plotting, please see examples/prediction_example.py.

Running this script will generate a plot comparing the ground truth data against the model's forecast, similar to the one shown below:

Additionally, we provide a script that makes predictions without Volume and Amount data, which can be found in examples/prediction_wo_vol_example.py.

🔧 Finetuning on Your Own Data (A-Share Market Example)

We provide a complete pipeline for finetuning Kronos on your own datasets. As an example, we demonstrate how to use Qlib to prepare data from the Chinese A-share market and conduct a simple backtest.

Disclaimer: This pipeline is intended as a demonstration to illustrate the finetuning process. It is a simplified example and not a production-ready quantitative trading system. A robust quantitative strategy requires more sophisticated techniques, such as portfolio optimization and risk factor neutralization, to achieve stable alpha.

The finetuning process is divided into four main steps:

Configuration: Set up paths and hyperparameters.
Data Preparation: Process and split your data using Qlib.
Model Finetuning: Finetune the Tokenizer and the Predictor models.
Backtesting: Evaluate the finetuned model's performance.

Prerequisites

First, ensure you have all dependencies from requirements.txt installed.
This pipeline relies on qlib. Please install it:
```
  pip install pyqlib
```
You will need to prepare your Qlib data. Follow the official Qlib guide to download and set up your data locally. The example scripts assume you are using daily frequency data.

Step 1: Configure Your Experiment

All settings for data, training, and model paths are centralized in finetune/config.py. Before running any scripts, please modify the following paths according to your environment:

qlib_data_path: Path to your local Qlib data directory.
dataset_path: Directory where the processed train/validation/test pickle files will be saved.
save_path: Base directory for saving model checkpoints.
backtest_result_path: Directory for saving backtesting results.
pretrained_tokenizer_path and pretrained_predictor_path: Paths to the pre-trained models you want to start from (can be local paths or Hugging Face model names).

You can also adjust other parameters like instrument, train_time_range, epochs, and batch_size to fit your specific task. If you don't use Comet.ml, set use_comet = False.

Step 2: Prepare the Dataset

Run the data preprocessing script. This script will load raw market data from your Qlib directory, process it, split it into training, validation, and test sets, and save them as pickle files.

python finetune/qlib_data_preprocess.py

After running, you will find train_data.pkl, val_data.pkl, and test_data.pkl in the directory specified by dataset_path in your config.

Step 3: Run the Finetuning

The finetuning process consists of two stages: finetuning the tokenizer and then the predictor. Both training scripts are designed for multi-GPU training using torchrun.

3.1 Finetune the Tokenizer

This step adjusts the tokenizer to the data distribution of your specific domain.

# Replace NUM_GPUS with the number of GPUs you want to use (e.g., 2)
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_tokenizer.py

The best tokenizer checkpoint will be saved to the path configured in config.py (derived from save_path and tokenizer_save_folder_name).

3.2 Finetune the Predictor

This step finetunes the main Kronos model for the forecasting task.

# Replace NUM_GPUS with the number of GPUs you want to use (e.g., 2)
torchrun --standalone --nproc_per_node=NUM_GPUS finetune/train_predictor.py

The best predictor checkpoint will be saved to the path configured in config.py.

Step 4: Evaluate with Backtesting

Finally, run the backtesting script to evaluate your finetuned model. This script loads the models, performs inference on the test set, generates prediction signals (e.g., forecasted price change), and runs a simple top-K strategy backtest.

# Specify the GPU for inference
python finetune/qlib_test.py --device cuda:0

The script will output a detailed performance analysis in your console and generate a plot showing the cumulative return curves of your strategy against the benchmark, similar to the one below:

💡 From Demo to Production: Important Considerations

Raw Signals vs. Pure Alpha: The signals generated by the model in this demo are raw predictions. In a real-world quantitative workflow, these signals would typically be fed into a portfolio optimization model. This model would apply constraints to neutralize exposure to common risk factors (e.g., market beta, style factors like size and value), thereby isolating the "pure alpha" and improving the strategy's robustness.
Data Handling: The provided QlibDataset is an example. For different data sources or formats, you will need to adapt the data loading and preprocessing logic.
Strategy and Backtesting Complexity: The simple top-K strategy used here is a basic starting point. Production-level strategies often incorporate more complex logic for portfolio construction, dynamic position sizing, and risk management (e.g., stop-loss/take-profit rules). Furthermore, a high-fidelity backtest should meticulously model transaction costs, slippage, and market impact to provide a more accurate estimate of real-world performance.

📝 AI-Generated Comments: Please note that many of the code comments within the finetune/ directory were generated by an AI assistant (Gemini 2.5 Pro) for explanatory purposes. While they aim to be helpful, they may contain inaccuracies. We recommend treating the code itself as the definitive source of logic.

📖 Citation

If you use Kronos in your research, we would appreciate a citation to our paper:

@misc{shi2025kronos,
      title={Kronos: A Foundation Model for the Language of Financial Markets}, 
      author={Yu Shi and Zongliang Fu and Shuo Chen and Bohan Zhao and Wei Xu and Changshui Zhang and Jian Li},
      year={2025},
      eprint={2508.02739},
      archivePrefix={arXiv},
      primaryClass={q-fin.ST},
      url={https://arxiv.org/abs/2508.02739}, 
}

📜 License

This project is licensed under the MIT License.

coleam00/Archon

The first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.

Archon

The first open-source harness builder for AI coding. Make AI coding deterministic and repeatable.

Archon is a workflow engine for AI coding agents. Define your development processes as YAML workflows - planning, implementation, validation, code review, PR creation - and run them reliably across all your projects.

Like what Dockerfiles did for infrastructure and GitHub Actions did for CI/CD - Archon does for AI coding workflows. Think n8n, but for software development.

Why Archon?

When you ask an AI agent to "fix this bug", what happens depends on the model's mood. It might skip planning. It might forget to run tests. It might write a PR description that ignores your template. Every run is different.

Archon fixes this. Encode your development process as a workflow. The workflow defines the phases, validation gates, and artifacts. The AI fills in the intelligence at each step, but the structure is deterministic and owned by you.

Repeatable - Same workflow, same sequence, every time. Plan, implement, validate, review, PR.
Isolated - Every workflow run gets its own git worktree. Run 5 fixes in parallel with no conflicts.
Fire and forget - Kick off a workflow, go do other work. Come back to a finished PR with review comments.
Composable - Mix deterministic nodes (bash scripts, tests, git ops) with AI nodes (planning, code generation, review). The AI only runs where it adds value.
Portable - Define workflows once in .archon/workflows/, commit them to your repo. They work the same from CLI, Web UI, Slack, Telegram, or GitHub.

What It Looks Like

Here's an example of an Archon workflow that plans, implements in a loop until tests pass, gets your approval, then creates the PR:

# .archon/workflows/build-feature.yaml
nodes:
  - id: plan
    prompt: "Explore the codebase and create an implementation plan"

  - id: implement
    depends_on: [plan]
    loop:                                      # AI loop - iterate until done
      prompt: "Read the plan. Implement the next task. Run validation."
      until: ALL_TASKS_COMPLETE
      fresh_context: true                      # Fresh session each iteration

  - id: run-tests
    depends_on: [implement]
    bash: "bun run validate"                   # Deterministic - no AI

  - id: review
    depends_on: [run-tests]
    prompt: "Review all changes against the plan. Fix any issues."

  - id: approve
    depends_on: [review]
    loop:                                      # Human approval gate
      prompt: "Present the changes for review. Address any feedback."
      until: APPROVED
      interactive: true                        # Pauses and waits for human input

  - id: create-pr
    depends_on: [approve]
    prompt: "Push changes and create a pull request"

Tell your coding agent what you want, and Archon handles the rest:

You: Use archon to add dark mode to the settings page

Agent: I'll run the archon-idea-to-pr workflow for this.
       → Creating isolated worktree on branch archon/task-dark-mode...
       → Planning...
       → Implementing (task 1/4)...
       → Implementing (task 2/4)...
       → Tests failing - iterating...
       → Tests passing after 2 iterations
       → Code review complete - 0 issues
       → PR ready: https://github.com/you/project/pull/47

Previous Version

Looking for the original Python-based Archon (task management + RAG)? It's fully preserved on the archive/v1-task-management-rag branch.

Getting Started

Most users should start with the Full Setup - it walks you through credentials, installs the Archon skill into your projects, and gives you the web dashboard.

Already have Claude Code and just want the CLI? Jump to the Quick Install.

Full Setup (5 minutes)

Clone the repo and use the guided setup wizard. This configures credentials, platform integrations, and copies the Archon skill into your target projects.

Prerequisites - Bun, Claude Code, and the GitHub CLI

Bun - bun.sh

# macOS/Linux
curl -fsSL https://bun.sh/install | bash

# Windows (PowerShell)
irm bun.sh/install.ps1 | iex

GitHub CLI - cli.github.com

# macOS
brew install gh

# Windows (via winget)
winget install GitHub.cli

# Linux (Debian/Ubuntu)
sudo apt install gh

Claude Code - claude.ai/code

# macOS/Linux/WSL
curl -fsSL https://claude.ai/install.sh | bash

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex

git clone https://github.com/coleam00/Archon
cd Archon
bun install
claude

Then say: "Set up Archon"

The setup wizard walks you through everything: CLI installation, authentication, platform selection, and copies the Archon skill to your target repo.

Quick Install (30 seconds)

Already have Claude Code set up? Install the standalone CLI binary and skip the wizard.

macOS / Linux

curl -fsSL https://archon.diy/install | bash

Windows (PowerShell)

irm https://archon.diy/install.ps1 | iex

Homebrew

brew install coleam00/archon/archon

Compiled binaries need a CLAUDE_BIN_PATH. The quick-install binaries don't bundle Claude Code. Install it separately, then point Archon at it:
# macOS / Linux / WSL
curl -fsSL https://claude.ai/install.sh | bash
export CLAUDE_BIN_PATH="$HOME/.local/bin/claude"

# Windows (PowerShell)
irm https://claude.ai/install.ps1 | iex
$env:CLAUDE_BIN_PATH = "$env:USERPROFILE\.local\bin\claude.exe"
Or set assistants.claude.claudeBinaryPath in ~/.archon/config.yaml. The Docker image ships Claude Code pre-installed. See AI Assistants → Binary path configuration for details.

Start Using Archon

Once you've completed either setup path, go to your project and start working:

cd /path/to/your/project
claude

Use archon to fix issue #42

What archon workflows do I have? When would I use each one?

The coding agent handles workflow selection, branch naming, and worktree isolation for you. Projects are registered automatically the first time they're used.

Important: Always run Claude Code from your target repo, not from the Archon repo. The setup wizard copies the Archon skill into your project so it works from there.

Web UI

Archon includes a web dashboard for chatting with your coding agent, running workflows, and monitoring activity. Binary installs: run archon serve to download and start the web UI in one step. From source: ask your coding agent to run the frontend from the Archon repo, or run bun run dev from the repo root yourself.

Register a project by clicking + next to "Project" in the chat sidebar - enter a GitHub URL or local path. Then start a conversation, invoke workflows, and watch progress in real time.

Key pages:

Chat - Conversation interface with real-time streaming and tool call visualization
Dashboard - Mission Control for monitoring running workflows, with filterable history by project, status, and date
Workflow Builder - Visual drag-and-drop editor for creating DAG workflows with loop nodes
Workflow Execution - Step-by-step progress view for any running or completed workflow

Monitoring hub: The sidebar shows conversations from all platforms - not just the web. Workflows kicked off from the CLI, messages from Slack or Telegram, GitHub issue interactions - everything appears in one place.

See the Web UI Guide for full documentation.

What Can You Automate?

Archon ships with workflows for common development tasks:

Workflow	What it does
`archon-assist`	General Q&A, debugging, exploration - full Claude Code agent with all tools
`archon-fix-github-issue`	Classify issue → investigate/plan → implement → validate → PR → smart review → self-fix
`archon-idea-to-pr`	Feature idea → plan → implement → validate → PR → 5 parallel reviews → self-fix
`archon-plan-to-pr`	Execute existing plan → implement → validate → PR → review → self-fix
`archon-issue-review-full`	Comprehensive fix + full multi-agent review pipeline for GitHub issues
`archon-smart-pr-review`	Classify PR complexity → run targeted review agents → synthesize findings
`archon-comprehensive-pr-review`	Multi-agent PR review (5 parallel reviewers) with automatic fixes
`archon-create-issue`	Classify problem → gather context → investigate → create GitHub issue
`archon-validate-pr`	Thorough PR validation testing both main and feature branches
`archon-resolve-conflicts`	Detect merge conflicts → analyze both sides → resolve → validate → commit
`archon-feature-development`	Implement feature from plan → validate → create PR
`archon-architect`	Architectural sweep, complexity reduction, codebase health improvement
`archon-refactor-safely`	Safe refactoring with type-check hooks and behavior verification
`archon-ralph-dag`	PRD implementation loop - iterate through stories until done
`archon-remotion-generate`	Generate or modify Remotion video compositions with AI
`archon-test-loop-dag`	Loop node test workflow - iterative counter until completion
`archon-piv-loop`	Guided Plan-Implement-Validate loop with human review between iterations

Archon ships 17 default workflows - run archon workflow list or describe what you want and the router picks the right one.

Or define your own. Default workflows are great starting points - copy one from .archon/workflows/defaults/ and customize it. Workflows are YAML files in .archon/workflows/, commands are markdown files in .archon/commands/. Same-named files in your repo override the bundled defaults. Commit them - your whole team runs the same process.

See Authoring Workflows and Authoring Commands.

Add a Platform

The Web UI and CLI work out of the box. Optionally connect a chat platform for remote access:

Platform	Setup time	Guide
Telegram	5 min	Telegram Guide
Slack	15 min	Slack Guide
GitHub Webhooks	15 min	GitHub Guide
Discord	5 min	Discord Guide

Architecture

┌─────────────────────────────────────────────────────────┐
│  Platform Adapters (Web UI, CLI, Telegram, Slack,       │
│                    Discord, GitHub)                      │
└──────────────────────────┬──────────────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│                     Orchestrator                        │
│          (Message Routing & Context Management)         │
└─────────────┬───────────────────────────┬───────────────┘
              │                           │
      ┌───────┴────────┐          ┌───────┴────────┐
      │                │          │                │
      ▼                ▼          ▼                ▼
┌───────────┐  ┌────────────┐  ┌──────────────────────────┐
│  Command  │  │  Workflow  │  │    AI Assistant Clients  │
│  Handler  │  │  Executor  │  │      (Claude / Codex)    │
│  (Slash)  │  │  (YAML)    │  │                          │
└───────────┘  └────────────┘  └──────────────────────────┘
      │              │                      │
      └──────────────┴──────────────────────┘
                           │
                           ▼
┌─────────────────────────────────────────────────────────┐
│              SQLite / PostgreSQL (7 Tables)             │
│   Codebases • Conversations • Sessions • Workflow Runs  │
│    Isolation Environments • Messages • Workflow Events  │
└─────────────────────────────────────────────────────────┘

Documentation

Full documentation is available at archon.diy.

Topic	Description
Getting Started	Setup guide (Web UI or CLI)
The Book of Archon	10-chapter narrative tutorial
CLI Reference	Full CLI reference
Authoring Workflows	Create custom YAML workflows
Authoring Commands	Create reusable AI commands
Configuration	All config options, env vars, YAML settings
AI Assistants	Claude and Codex setup details
Deployment	Docker, VPS, production setup
Architecture	System design and internals
Troubleshooting	Common issues and fixes

Telemetry

Archon sends a single anonymous event — workflow_invoked — each time a workflow starts, so maintainers can see which workflows get real usage and prioritize accordingly. No PII, ever.

What's collected: the workflow name, the workflow description (both authored by you in YAML), the platform that triggered it (cli, web, slack, etc.), the Archon version, and a random install UUID stored at ~/.archon/telemetry-id. Nothing else.

What's not collected: your code, prompts, messages, git remotes, file paths, usernames, tokens, AI output, workflow node details — none of it.

Opt out: set any of these in your environment:

ARCHON_TELEMETRY_DISABLED=1
DO_NOT_TRACK=1        # de facto standard honored by Astro, Bun, Prisma, Nuxt, etc.

Self-host PostHog or use a different project by setting POSTHOG_API_KEY and POSTHOG_HOST.

Contributing

Contributions welcome! See the open issues for things to work on.

Please read CONTRIBUTING.md before submitting a pull request.

License

MIT

TauricResearch/TradingAgents

TradingAgents: Multi-Agents LLM Financial Trading Framework

TradingAgents: Multi-Agents LLM Financial Trading Framework

News

[2026-03] TradingAgents v0.2.3 released with multi-language support, GPT-5.4 family models, unified model catalog, backtesting date fidelity, and proxy support.
[2026-03] TradingAgents v0.2.2 released with GPT-5.4/Gemini 3.1/Claude 4.6 model coverage, five-tier rating scale, OpenAI Responses API, Anthropic effort control, and cross-platform stability.
[2026-02] TradingAgents v0.2.0 released with multi-provider LLM support (GPT-5.x, Gemini 3.x, Claude 4.x, Grok 4.x) and improved system architecture.
[2026-01] Trading-R1 Technical Report released, with Terminal expected to land soon.

🎉 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.

So we decided to fully open-source the framework. Looking forward to building impactful projects with you!

TradingAgents Framework

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.

TradingAgents 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.

Our framework decomposes complex trading tasks into specialized roles. This ensures the system achieves a robust, scalable approach to market analysis and decision-making.

Analyst Team

Fundamentals Analyst: Evaluates company financials and performance metrics, identifying intrinsic values and potential red flags.
Sentiment Analyst: Analyzes social media and public sentiment using sentiment scoring algorithms to gauge short-term market mood.
News Analyst: Monitors global news and macroeconomic indicators, interpreting the impact of events on market conditions.
Technical Analyst: Utilizes technical indicators (like MACD and RSI) to detect trading patterns and forecast price movements.

Researcher Team

Comprises both bullish and bearish researchers who critically assess the insights provided by the Analyst Team. Through structured debates, they balance potential gains against inherent risks.

Trader Agent

Composes reports from the analysts and researchers to make informed trading decisions. It determines the timing and magnitude of trades based on comprehensive market insights.

Risk Management and Portfolio Manager

Continuously evaluates portfolio risk by assessing market volatility, liquidity, and other risk factors. The risk management team evaluates and adjusts trading strategies, providing assessment reports to the Portfolio Manager for final decision.
The Portfolio Manager approves/rejects the transaction proposal. If approved, the order will be sent to the simulated exchange and executed.

Installation and CLI

Installation

Clone TradingAgents:

git clone https://github.com/TauricResearch/TradingAgents.git
cd TradingAgents

Create a virtual environment in any of your favorite environment managers:

conda create -n tradingagents python=3.13
conda activate tradingagents

Install the package and its dependencies:

pip install .

Docker

Alternatively, run with Docker:

cp .env.example .env  # add your API keys
docker compose run --rm tradingagents

For local models with Ollama:

docker compose --profile ollama run --rm tradingagents-ollama

Required APIs

TradingAgents supports multiple LLM providers. Set the API key for your chosen provider:

export OPENAI_API_KEY=...          # OpenAI (GPT)
export GOOGLE_API_KEY=...          # Google (Gemini)
export ANTHROPIC_API_KEY=...       # Anthropic (Claude)
export XAI_API_KEY=...             # xAI (Grok)
export DEEPSEEK_API_KEY=...        # DeepSeek
export DASHSCOPE_API_KEY=...       # Qwen (Alibaba DashScope)
export ZHIPU_API_KEY=...           # GLM (Zhipu)
export OPENROUTER_API_KEY=...      # OpenRouter
export ALPHA_VANTAGE_API_KEY=...   # Alpha Vantage

For enterprise providers (e.g. Azure OpenAI, AWS Bedrock), copy .env.enterprise.example to .env.enterprise and fill in your credentials.

For local models, configure Ollama with llm_provider: "ollama" in your config.

Alternatively, copy .env.example to .env and fill in your keys:

cp .env.example .env

CLI Usage

Launch the interactive CLI:

tradingagents          # installed command
python -m cli.main     # alternative: run directly from source

You will see a screen where you can select your desired tickers, analysis date, LLM provider, research depth, and more.

An interface will appear showing results as they load, letting you track the agent's progress as it runs.

TradingAgents Package

Implementation Details

We built TradingAgents with LangGraph to ensure flexibility and modularity. The framework supports multiple LLM providers: OpenAI, Google, Anthropic, xAI, OpenRouter, and Ollama.

Python Usage

To 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
from tradingagents.default_config import DEFAULT_CONFIG

ta = TradingAgentsGraph(debug=True, config=DEFAULT_CONFIG.copy())

# forward propagate
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)

You can also adjust the default configuration to set your own choice of LLMs, debate rounds, etc.

from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG

config = DEFAULT_CONFIG.copy()
config["llm_provider"] = "openai"        # openai, google, anthropic, xai, openrouter, ollama
config["deep_think_llm"] = "gpt-5.4"     # Model for complex reasoning
config["quick_think_llm"] = "gpt-5.4-mini" # Model for quick tasks
config["max_debate_rounds"] = 2

ta = TradingAgentsGraph(debug=True, config=config)
_, decision = ta.propagate("NVDA", "2026-01-15")
print(decision)

See tradingagents/default_config.py for all configuration options.

Contributing

We welcome contributions from the community! Whether it's fixing a bug, improving documentation, or suggesting a new feature, your input helps make this project better. If you are interested in this line of research, please consider joining our open-source financial AI research community Tauric Research.

Citation

Please reference our work if you find TradingAgents provides you with some help 😃

@misc{xiao2025tradingagentsmultiagentsllmfinancial,
      title={TradingAgents: Multi-Agents LLM Financial Trading Framework}, 
      author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},
      year={2025},
      eprint={2412.20138},
      archivePrefix={arXiv},
      primaryClass={q-fin.TR},
      url={https://arxiv.org/abs/2412.20138}, 
}

microsoft/VibeVoice

Open-Source Frontier Voice AI

🎙️ VibeVoice: Open-Source Frontier Voice AI

📰 News

🎉 Vibing, an intelligent voice input method built by the community, is now powered by VibeVoice-ASR. Download: macOS | Windows EXE Installer (Recommended) | Windows ZIP (Portable)

https://github.com/user-attachments/assets/db0bb23f-ae06-4135-a66a-1ff1669f4f84

2026-03-06: 🚀 VibeVoice ASR is now part of a Transformers release! You can now use our speech recognition model directly through the Hugging Face Transformers library for seamless integration into your projects.

2026-01-21: 📣 We open-sourced VibeVoice-ASR, a unified speech-to-text model designed to handle 60-minute long-form audio in a single pass, generating structured transcriptions containing Who (Speaker), When (Timestamps), and What (Content), with support for User-Customized Context. Try it in Playground.

⭐️ VibeVoice-ASR is natively multilingual, supporting over 50 languages — check the supported languages for details.
🔥 The VibeVoice-ASR finetuning code is now available!
⚡️ vLLM inference is now supported for faster inference; see vllm-asr for more details.
📑 VibeVoice-ASR Technique Report is available.

2025-12-16: 📣 We added experimental speakers to VibeVoice‑Realtime‑0.5B for exploration, including multilingual voices in nine languages (DE, FR, IT, JP, KR, NL, PL, PT, ES) and 11 distinct English style voices. Try it. More speaker types will be added over time.

2025-12-03: 📣 We open-sourced VibeVoice‑Realtime‑0.5B, a real‑time text‑to‑speech model that supports streaming text input and robust long-form speech generation. Try it on Colab.

2025-09-05: VibeVoice is an open-source research framework intended to advance collaboration in the speech synthesis community. After release, we discovered instances where the tool was used in ways inconsistent with the stated intent. Since responsible use of AI is one of Microsoft’s guiding principles, we have removed the VibeVoice-TTS code from this repository.

2025-08-25: 📣 We open-sourced VibeVoice-TTS, a long-form multi-speaker text-to-speech model that can synthesize speech up to 90 minutes long with up to 4 distinct speakers. — accepted as an Oral at ICLR 2026! 🔥

Overview

VibeVoice is a family of open-source frontier voice AI models that includes both Text-to-Speech (TTS) and Automatic Speech Recognition (ASR) models.

A core innovation of VibeVoice is its use of continuous speech tokenizers (Acoustic and Semantic) operating at an ultra-low frame rate of 7.5 Hz. These tokenizers efficiently preserve audio fidelity while significantly boosting computational efficiency for processing long sequences. VibeVoice employs a next-token diffusion framework, leveraging a Large Language Model (LLM) to understand textual context and dialogue flow, and a diffusion head to generate high-fidelity acoustic details.

For more information, demos, and examples, please visit our Project Page.

Model	Weight	Quick Try
VibeVoice-ASR-7B	HF Link	Playground
VibeVoice-TTS-1.5B	HF Link	Disabled
VibeVoice-Realtime-0.5B	HF Link	Colab

Models

1. 📖 VibeVoice-ASR - Long-form Speech Recognition

VibeVoice-ASR is a unified speech-to-text model designed to handle 60-minute long-form audio in a single pass, generating structured transcriptions containing Who (Speaker), When (Timestamps), and What (Content), with support for Customized Hotwords.

🕒 60-minute Single-Pass Processing: Unlike conventional ASR models that slice audio into short chunks (often losing global context), VibeVoice ASR accepts up to 60 minutes of continuous audio input within 64K token length. This ensures consistent speaker tracking and semantic coherence across the entire hour.
👤 Customized Hotwords: Users can provide customized hotwords (e.g., specific names, technical terms, or background info) to guide the recognition process, significantly improving accuracy on domain-specific content.
📝 Rich Transcription (Who, When, What): The model jointly performs ASR, diarization, and timestamping, producing a structured output that indicates who said what and when.

📖 Documentation | 🤗 Hugging Face | 🎮 Playground | 🛠️ Finetuning | 📊 Paper

https://github.com/user-attachments/assets/acde5602-dc17-4314-9e3b-c630bc84aefa

2. 🎙️ VibeVoice-TTS - Long-form Multi-speaker TTS

Best for: Long-form conversational audio, podcasts, multi-speaker dialogues

⏱️ 90-minute Long-form Generation: Synthesizes conversational/single-speaker speech up to 90 minutes in a single pass, maintaining speaker consistency and semantic coherence throughout.
👥 Multi-speaker Support: Supports up to 4 distinct speakers in a single conversation, with natural turn-taking and speaker consistency across long dialogues.
🎭 Expressive Speech: Generates expressive, natural-sounding speech that captures conversational dynamics and emotional nuances.
🌐 Multi-lingual Support: Supports English, Chinese and other languages.

📖 Documentation | 🤗 Hugging Face | 📊 Paper

English

https://github.com/user-attachments/assets/0967027c-141e-4909-bec8-091558b1b784

Chinese

https://github.com/user-attachments/assets/322280b7-3093-4c67-86e3-10be4746c88f

Cross-Lingual

https://github.com/user-attachments/assets/838d8ad9-a201-4dde-bb45-8cd3f59ce722

Spontaneous Singing

https://github.com/user-attachments/assets/6f27a8a5-0c60-4f57-87f3-7dea2e11c730

Long Conversation with 4 people

https://github.com/user-attachments/assets/a357c4b6-9768-495c-a576-1618f6275727

3. ⚡ VibeVoice-Streaming - Real-time Streaming TTS

VibeVoice-Realtime is a lightweight real‑time text-to-speech model supporting streaming text input and robust long-form speech generation.

Parameter size: 0.5B (deployment-friendly)
Real-time TTS (~300 milliseconds first audible latency)
Streaming text input
Robust long-form speech generation (~10 minutes)

📖 Documentation | 🤗 Hugging Face | 🚀 Colab

https://github.com/user-attachments/assets/0901d274-f6ae-46ef-a0fd-3c4fba4f76dc

Contributing

Please see CONTRIBUTING.md for detailed contribution guidelines.

⚠️ Risks and Limitations

While efforts have been made to optimize it through various techniques, it may still produce outputs that are unexpected, biased, or inaccurate. VibeVoice inherits any biases, errors, or omissions produced by its base model (specifically, Qwen2.5 1.5b in this release). Potential for Deepfakes and Disinformation: High-quality synthetic speech can be misused to create convincing fake audio content for impersonation, fraud, or spreading disinformation. Users must ensure transcripts are reliable, check content accuracy, and avoid using generated content in misleading ways. Users are expected to use the generated content and to deploy the models in a lawful manner, in full compliance with all applicable laws and regulations in the relevant jurisdictions. It is best practice to disclose the use of AI when sharing AI-generated content.

We do not recommend using VibeVoice in commercial or real-world applications without further testing and development. This model is intended for research and development purposes only. Please use responsibly.

Star History

OpenBMB/VoxCPM

VoxCPM2: Tokenizer-Free TTS for Multilingual Speech Generation, Creative Voice Design, and True-to-Life Cloning

English | 中文

👋 Join our community for discussion and support!
Feishu | Discord

VoxCPM is a tokenizer-free Text-to-Speech system that directly generates continuous speech representations via an end-to-end diffusion autoregressive architecture, bypassing discrete tokenization to achieve highly natural and expressive synthesis.

VoxCPM2 is the latest major release — a 2B parameter model trained on over 2 million hours of multilingual speech data, now supporting 30 languages, Voice Design, Controllable Voice Cloning, and 48kHz studio-quality audio output. Built on a MiniCPM-4 backbone.

✨ Highlights

🌍 30-Language Multilingual — Input text in any of the 30 supported languages and synthesize directly, no language tag needed
🎨 Voice Design — Create a brand-new voice from a natural-language description alone (gender, age, tone, emotion, pace …), no reference audio required
🎛️ Controllable Cloning — Clone any voice from a short reference clip, with optional style guidance to steer emotion, pace, and expression while preserving the original timbre
🎙️ Ultimate Cloning — Reproduce every vocal nuance: provide both reference audio and its transcript, and the model continues seamlessly from the reference, faithfully preserving every vocal detail — timbre, rhythm, emotion, and style (same as VoxCPM1.5)
🔊 48kHz High-Quality Audio — Accepts 16kHz reference audio and directly outputs 48kHz studio-quality audio via AudioVAE V2's asymmetric encode/decode design, with built-in super-resolution — no external upsampler needed
🧠 Context-Aware Synthesis — Automatically infers appropriate prosody and expressiveness from text content
⚡ Real-Time Streaming — RTF as low as ~0.3 on NVIDIA RTX 4090, and ~0.13 accelerated by Nano-vLLM or vLLM-Omni — official vLLM omni-modal serving for VoxCPM2 with PagedAttention and an OpenAI-compatible API
📜 Fully Open-Source & Commercial-Ready — Weights and code released under the Apache-2.0 license, free for commercial use

🌍 Supported Languages (30)

Arabic, Burmese, Chinese, Danish, Dutch, English, Finnish, French, German, Greek, Hebrew, Hindi, Indonesian, Italian, Japanese, Khmer, Korean, Lao, Malay, Norwegian, Polish, Portuguese, Russian, Spanish, Swahili, Swedish, Tagalog, Thai, Turkish, Vietnamese

Chinese Dialect: 四川话, 粤语, 吴语, 东北话, 河南话, 陕西话, 山东话, 天津话, 闽南话

News

[2026.04] 🔥 We release VoxCPM2 — 2B, 30 languages, Voice Design & Controllable Voice Cloning, 48kHz audio output! Weights | Docs | Playground
[2025.12] 🎉 Open-source VoxCPM1.5 weights with SFT & LoRA fine-tuning. (🏆 #1 GitHub Trending)
[2025.09] 🔥 Release VoxCPM Technical Report.
[2025.09] 🎉 Open-source VoxCPM-0.5B weights (🏆 #1 HuggingFace Trending)

🚀 Quick Start

Installation

pip install voxcpm

Requirements: Python ≥ 3.10 (❤️.13), PyTorch ≥ 2.5.0, CUDA ≥ 12.0. See Quick Start Docs for details.

Python API

🗣️ Text-to-Speech

from voxcpm import VoxCPM
import soundfile as sf

model = VoxCPM.from_pretrained(
  "openbmb/VoxCPM2",
  load_denoiser=False,
)

wav = model.generate(
    text="VoxCPM2 is the current recommended release for realistic multilingual speech synthesis.",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("demo.wav", wav, model.tts_model.sample_rate)
print("saved: demo.wav")

If you prefer downloading from ModelScope first, you can use:

pip install modelscope

from modelscope import snapshot_download
snapshot_download("OpenBMB/VoxCPM2", local_dir='./pretrained_models/VoxCPM2') # specify the local directory to save the model

from voxcpm import VoxCPM
import soundfile as sf
model = VoxCPM.from_pretrained("./pretrained_models/VoxCPM2", load_denoiser=False)

wav = model.generate(
    text="VoxCPM2 is the current recommended release for realistic multilingual speech synthesis.",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("demo.wav", wav, model.tts_model.sample_rate)

🎨 Voice Design

Create a voice from a natural-language description — no reference audio needed. Format: put the description in parentheses at the start of text(e.g. "(your voice description)The text to synthesize."):

wav = model.generate(
    text="(A young woman, gentle and sweet voice)Hello, welcome to VoxCPM2!",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("voice_design.wav", wav, model.tts_model.sample_rate)

🎛️ Controllable Voice Cloning

Upload a reference audio. The model clones the timbre, and you can still use control instructions to adjust speed, emotion, or style.

wav = model.generate(
    text="This is a cloned voice generated by VoxCPM2.",
    reference_wav_path="path/to/voice.wav",
)
sf.write("clone.wav", wav, model.tts_model.sample_rate)

wav = model.generate(
    text="(slightly faster, cheerful tone)This is a cloned voice with style control.",
    reference_wav_path="path/to/voice.wav",
    cfg_value=2.0,
    inference_timesteps=10,
)
sf.write("controllable_clone.wav", wav, model.tts_model.sample_rate)

🎙️ Ultimate Cloning

Provide both the reference audio and its exact transcript for audio-continuation-based cloning with every vocal nuance reproduced. For maximum cloning similarity, pass the same reference clip to both reference_wav_path and prompt_wav_path as shown below:

wav = model.generate(
    text="This is an ultimate cloning demonstration using VoxCPM2.",
    prompt_wav_path="path/to/voice.wav",
    prompt_text="The transcript of the reference audio.",
    reference_wav_path="path/to/voice.wav", # optional, for better simliarity 
)
sf.write("hifi_clone.wav", wav, model.tts_model.sample_rate)

🔄 Streaming API

import numpy as np

chunks = []
for chunk in model.generate_streaming(
    text="Streaming text to speech is easy with VoxCPM!",
):
    chunks.append(chunk)
wav = np.concatenate(chunks)
sf.write("streaming.wav", wav, model.tts_model.sample_rate)

CLI Usage

# Voice design (no reference audio needed)
voxcpm design \
  --text "VoxCPM2 brings studio-quality multilingual speech synthesis." \
  --output out.wav

# Controllable voice cloning with style control
voxcpm design \
  --text "VoxCPM2 brings studio-quality multilingual speech synthesis." \
  --control "Young female voice, warm and gentle, slightly smiling" \
  --output out.wav

# Voice cloning (reference audio)
voxcpm clone \
  --text "This is a voice cloning demo." \
  --reference-audio path/to/voice.wav \
  --output out.wav

# Ultimate cloning (prompt audio + transcript)
voxcpm clone \
  --text "This is a voice cloning demo." \
  --prompt-audio path/to/voice.wav \
  --prompt-text "reference transcript" \
  --reference-audio path/to/voice.wav \ # optional, for better simliarity
  --output out.wav

# Batch processing
voxcpm batch --input examples/input.txt --output-dir outs

# Help
voxcpm --help

Web Demo

python app.py --port 8808  # then open in browser: http://localhost:8808

🚢 Production Deployment (Nano-vLLM)

For high-throughput serving, use Nano-vLLM-VoxCPM — a dedicated inference engine built on Nano-vLLM with concurrent request support and an async API.

pip install nano-vllm-voxcpm

from nanovllm_voxcpm import VoxCPM
import numpy as np, soundfile as sf

server = VoxCPM.from_pretrained(model="/path/to/VoxCPM", devices=[0])
chunks = list(server.generate(target_text="Hello from VoxCPM!"))
sf.write("out.wav", np.concatenate(chunks), 48000)
server.stop()

RTF as low as ~0.13 on NVIDIA RTX 4090 (vs ~0.3 with the standard PyTorch implementation), with support for batched concurrent requests and a FastAPI HTTP server. See the Nano-vLLM-VoxCPM repo for deployment details.

🏭 Production Serving (vLLM-Omni)

For production multi-tenant deployments, use vLLM-Omni — the official vLLM project's omni-modal extension with native VoxCPM2 support. PagedAttention KV cache, continuous batching, and a drop-in OpenAI-compatible /v1/audio/speech endpoint.

# Install from source (latest main — vllm-omni is rapidly evolving)
uv pip install vllm==0.19.0 --torch-backend=auto
git clone https://github.com/vllm-project/vllm-omni.git && cd vllm-omni
uv pip install -e .

See the vLLM-Omni installation guide for other platforms (ROCm, XPU, MUSA, NPU) and Docker images.

# Launch an OpenAI-compatible TTS server (--omni enables omni-modal serving)
vllm serve openbmb/VoxCPM2 --omni --port 8000

# Call it from any OpenAI client
curl http://localhost:8000/v1/audio/speech \
  -H "Content-Type: application/json" \
  -d '{"model":"openbmb/VoxCPM2","input":"Hello from VoxCPM2 on vLLM-Omni!","voice":"default"}' \
  --output out.wav

Built on the upstream vLLM scheduler, with batched concurrent requests, streaming chunk delivery, and multi-GPU deployment out of the box. See the VoxCPM2 example for full deployment recipes.

Full parameter reference, multi-scenario examples, and voice cloning tips → Quick Start Guide | Usage Guide | Cookbook

📦 Models & Versions

	VoxCPM2	VoxCPM1.5	VoxCPM-0.5B
Status	🟢 Latest	Stable	Legacy
Backbone Parameters	2B	0.6B	0.5B
Audio Sample Rate	48kHz	44.1kHz	16kHz
LM Token Rate	6.25Hz	6.25Hz	12.5Hz
Languages	30	2 (zh, en)	2 (zh, en)
Cloning Mode	Isolated Reference & Continuation	Continuation only	Continuation only
Voice Design	✅	—	—
Controllable Voice Cloning	✅	—	—
SFT / LoRA	✅	✅	✅
RTF (RTX 4090)	~0.30	~0.15	~0.17
RTF in Nano-VLLM (RTX 4090)	~0.13	~0.08	~0.10
VRAM	~8 GB	~6 GB	~5 GB
Weights	🤗 HF / MS	🤗 HF / MS	🤗 HF / MS
Technical Report	Coming soon	—	arXiv ICLR 2026
Demo Page	Audio Samples	—	Audio Samples

VoxCPM2 is built on a tokenizer-free, diffusion autoregressive paradigm. The model operates entirely in the latent space of AudioVAE V2, following a four-stage pipeline: LocEnc → TSLM → RALM → LocDiT, enabling rich expressiveness and 48kHz native audio output.

For full architectural details, VoxCPM2-specific upgrades, and a model comparison table, see the Architecture Design.

📊 Performance

VoxCPM2 achieves state-of-the-art or comparable results on public zero-shot and controllable TTS benchmarks.

Seed-TTS-eval

Seed-TTS-eval WER(⬇)&SIM(⬆) Results (click to expand)

Model	Parameters	Open-Source	test-EN		test-ZH		test-Hard
			WER/%⬇	SIM/%⬆	CER/%⬇	SIM/%⬆	CER/%⬇	SIM/%⬆
MegaTTS3	0.5B	❌	2.79	77.1	1.52	79.0	-	-
DiTAR	0.6B	❌	1.69	73.5	1.02	75.3	-	-
CosyVoice3	0.5B	❌	2.02	71.8	1.16	78.0	6.08	75.8
CosyVoice3	1.5B	❌	2.22	72.0	1.12	78.1	5.83	75.8
Seed-TTS	-	❌	2.25	76.2	1.12	79.6	7.59	77.6
MiniMax-Speech	-	❌	1.65	69.2	0.83	78.3	-	-
F5-TTS	0.3B	✅	2.00	67.0	1.53	76.0	8.67	71.3
MaskGCT	1B	✅	2.62	71.7	2.27	77.4	-	-
CosyVoice	0.3B	✅	4.29	60.9	3.63	72.3	11.75	70.9
CosyVoice2	0.5B	✅	3.09	65.9	1.38	75.7	6.83	72.4
SparkTTS	0.5B	✅	3.14	57.3	1.54	66.0	-	-
FireRedTTS	0.5B	✅	3.82	46.0	1.51	63.5	17.45	62.1
FireRedTTS-2	1.5B	✅	1.95	66.5	1.14	73.6	-	-
Qwen2.5-Omni	7B	✅	2.72	63.2	1.70	75.2	7.97	74.7
Qwen3-Omni	30B-A3B	✅	1.39	-	1.07	-	-	-
OpenAudio-s1-mini	0.5B	✅	1.94	55.0	1.18	68.5	23.37	64.3
IndexTTS2	1.5B	✅	2.23	70.6	1.03	76.5	7.12	75.5
VibeVoice	1.5B	✅	3.04	68.9	1.16	74.4	-	-
HiggsAudio-v2	3B	✅	2.44	67.7	1.50	74.0	55.07	65.6
VoxCPM-0.5B	0.6B	✅	1.85	72.9	0.93	77.2	8.87	73.0
VoxCPM1.5	0.8B	✅	2.12	71.4	1.18	77.0	7.74	73.1
MOSS-TTS		✅	1.85	73.4	1.20	78.8	-	-
Qwen3-TTS	1.7B	✅	1.23	71.7	1.22	77.0	6.76	74.8
FishAudio S2	4B	✅	0.99	-	0.54	-	5.99	-
LongCat-Audio-DiT	3.5B	✅	1.50	78.6	1.09	81.8	6.04	79.7
VoxCPM2	2B	✅	1.84	75.3	0.97	79.5	8.13	75.3

CV3-eval

CV3-eval Multilingual WER/CER(⬇) Results (click to expand)

Model	zh	en	hard-zh	hard-en	ja	ko	de	es	fr	it	ru
CosyVoice2	4.08	6.32	12.58	11.96	9.13	19.7	-	-	-	-	-
CosyVoice3-1.5B	3.91	4.99	9.77	10.55	7.57	5.69	6.43	4.47	11.8	10.5	6.64
Fish Audio S2	2.65	2.43	9.10	4.40	3.96	2.76	2.22	2.00	6.26	2.04	2.78
VoxCPM2	3.65	5.00	8.55	8.48	5.96	5.69	4.77	3.80	9.85	4.25	5.21

MiniMax-Multilingual-Test

Minimax-MLS-test WER(⬇) Results (click to expand)

Language	Minimax	ElevenLabs	Qwen3-TTS	FishAudio S2	VoxCPM2
Arabic	1.665	1.666	–	3.500	13.046
Cantonese	34.111	51.513	–	30.670	38.584
Chinese	2.252	16.026	0.928	0.730	1.136
Czech	3.875	2.108	–	2.840	24.132
Dutch	1.143	0.803	–	0.990	0.913
English	2.164	2.339	0.934	1.620	2.289
Finnish	4.666	2.964	–	3.330	2.632
French	4.099	5.216	2.858	3.050	4.534
German	1.906	0.572	1.235	0.550	0.679
Greek	2.016	0.991	–	5.740	2.844
Hindi	6.962	5.827	–	14.640	19.699
Indonesian	1.237	1.059	–	1.460	1.084
Italian	1.543	1.743	0.948	1.270	1.563
Japanese	3.519	10.646	3.823	2.760	4.628
Korean	1.747	1.865	1.755	1.180	1.962
Polish	1.415	0.766	–	1.260	1.141
Portuguese	1.877	1.331	1.526	1.140	1.938
Romanian	2.878	1.347	–	10.740	21.577
Russian	4.281	3.878	3.212	2.400	3.634
Spanish	1.029	1.084	1.126	0.910	1.438
Thai	2.701	73.936	–	4.230	2.961
Turkish	1.52	0.699	–	0.870	0.817
Ukrainian	1.082	0.997	–	2.300	6.316
Vietnamese	0.88	73.415	–	7.410	3.307

Minimax-MLS-test SIM(⬆) Results (click to expand)

Language	Minimax	ElevenLabs	Qwen3-TTS	FishAudio S2	VoxCPM2
Arabic	73.6	70.6	–	75.0	79.1
Cantonese	77.8	67.0	–	80.5	83.5
Chinese	78.0	67.7	79.9	81.6	82.5
Czech	79.6	68.5	–	79.8	78.3
Dutch	73.8	68.0	–	73.0	80.8
English	75.6	61.3	77.5	79.7	85.4
Finnish	83.5	75.9	–	81.9	89.0
French	62.8	53.5	62.8	69.8	73.5
German	73.3	61.4	77.5	76.7	80.3
Greek	82.6	73.3	–	79.5	86.0
Hindi	81.8	73.0	–	82.1	85.6
Indonesian	72.9	66.0	–	76.3	80.0
Italian	69.9	57.9	81.7	74.7	78.0
Japanese	77.6	73.8	78.8	79.6	82.8
Korean	77.6	70.0	79.9	81.7	83.3
Polish	80.2	72.9	–	81.9	88.4
Portuguese	80.5	71.1	81.7	78.1	83.7
Romanian	80.9	69.9	–	73.3	79.7
Russian	76.1	67.6	79.2	79.0	81.1
Spanish	76.2	61.5	81.4	77.6	83.1
Thai	80.0	58.8	–	78.6	84.0
Turkish	77.9	59.6	–	83.5	87.1
Ukrainian	73.0	64.7	–	74.7	79.8
Vietnamese	74.3	36.9	–	74.0	80.6

Internal 30-Language ASR Benchmark

We additionally run an internal multilingual intelligibility benchmark with 30 languages × 500 samples. ASR transcription is evaluated via Gemini 3.1 Flash Lite API.

Internal 30-Language ASR Benchmark (click to expand)

Language	Metric	VoxCPM2	Fish S2-Pro
ar (Arabic)	CER	1.23%	0.30%
da (Danish)	WER	2.70%	3.52%
de (German)	WER	0.96%	0.64%
el (Greek)	WER	3.17%	4.61%
en (English)	WER	0.42%	1.03%
es (Spanish)	WER	1.33%	0.64%
fi (Finnish)	WER	2.24%	2.80%
fr (French)	WER	2.16%	2.34%
he (Hebrew)	CER	2.98%	15.27%
hi (Hindi)	CER	0.79%	0.91%
id (Indonesian)	WER	1.36%	1.68%
it (Italian)	WER	1.65%	1.08%
ja (Japanese)	CER	2.40%	1.82%
km (Khmer)	CER	2.05%	75.15%
ko (Korean)	CER	0.95%	0.29%
lo (Lao)	CER	1.90%	87.40%
ms (Malay)	WER	1.75%	1.41%
my (Burmese)	CER	1.42%	85.27%
nl (Dutch)	WER	1.25%	1.68%
no (Norwegian)	WER	2.49%	3.76%
pl (Polish)	WER	1.90%	1.65%
pt (Portuguese)	WER	1.48%	1.49%
ru (Russian)	WER	0.90%	0.86%
sv (Swedish)	WER	2.22%	2.63%
sw (Swahili)	CER	1.07%	2.02%
th (Thai)	CER	0.94%	1.92%
tl (Tagalog)	WER	2.63%	4.00%
tr (Turkish)	WER	1.65%	1.65%
vi (Vietnamese)	WER	1.56%	5.56%
zh (Chinese)	CER	0.92%	1.02%
Average (30 languages)		1.68%	-

InstructTTSEval

Instruction-Guided Voice Design Results (click to expand)

Model	InstructTTSEval-ZH			InstructTTSEval-EN
	APS⬆	DSD⬆	RP⬆	APS⬆	DSD⬆	RP⬆
Hume	–	–	–	83.0	75.3	54.3
VoxInstruct	47.5	52.3	42.6	54.9	57.0	39.3
Parler-tts-mini	–	–	–	63.4	48.7	28.6
Parler-tts-large	–	–	–	60.0	45.9	31.2
PromptTTS	–	–	–	64.3	47.2	31.4
PromptStyle	–	–	–	57.4	46.4	30.9
VoiceSculptor	75.7	64.7	61.5	–	–	–
Mimo-Audio-7B-Instruct	75.7	74.3	61.5	80.6	77.6	59.5
Qwen3TTS-12Hz-1.7B-VD	85.2	81.1	65.1	82.9	82.4	68.4
VoxCPM2	85.2	71.5	60.8	84.2	83.2	71.4

⚙️ Fine-tuning

VoxCPM supports both full fine-tuning (SFT) and LoRA fine-tuning. With as little as 5–10 minutes of audio, you can adapt to a specific speaker, language, or domain.

# LoRA fine-tuning (parameter-efficient, recommended)
python scripts/train_voxcpm_finetune.py \
    --config_path conf/voxcpm_v2/voxcpm_finetune_lora.yaml

# Full fine-tuning
python scripts/train_voxcpm_finetune.py \
    --config_path conf/voxcpm_v2/voxcpm_finetune_all.yaml

# WebUI for training & inference
python lora_ft_webui.py   # then open http://localhost:7860

Full guide → Fine-tuning Guide (data preparation, configuration, training, LoRA hot-swapping, FAQ)

📚 Documentation

Full documentation: voxcpm.readthedocs.io

Topic	Link
Quick Start & Installation	Quick Start
Usage Guide & Cookbook	User Guide
VoxCPM Series	Models
Fine-tuning (SFT & LoRA)	Fine-tuning Guide
FAQ & Troubleshooting	FAQ

🌟 Ecosystem & Community

Project	Description
Nano-vLLM	High-throughput and Fast GPU serving
vLLM-Omni	Official vLLM omni-modal serving for VoxCPM2 — PagedAttention, OpenAI-compatible API
VoxCPM.cpp	GGML/GGUF: CPU, CUDA, Vulkan inference
VoxCPM-ONNX	ONNX export for CPU inference
VoxCPMANE	Apple Neural Engine backend
voxcpm_rs	Rust re-implementation
ComfyUI-VoxCPM	ComfyUI node-based workflows
ComfyUI_RH_VoxCPM	Feature-complete ComfyUI workflow for VoxCPM 2 with multi-speaker generation, LoRA, and auto-ASR
ComfyUI-VoxCPMTTS	ComfyUI TTS extension
TTS WebUI	Browser-based TTS extension

See the full Ecosystem in the docs. Community projects are not officially maintained by OpenBMB. Built something cool? Open an issue or PR to add it!

⚠️ Risks and Limitations

Potential for Misuse: VoxCPM's voice cloning can generate highly realistic synthetic speech. It is strictly forbidden to use VoxCPM for impersonation, fraud, or disinformation. We strongly recommend clearly marking any AI-generated content.
Controllable Generation Stability: Voice Design and Controllable Voice Cloning results can vary between runs — you may try to generate 1~3 times to obtain the desired voice or style. We are actively working on improving controllability consistency.
Language Coverage: VoxCPM2 officially supports 30 languages. For languages not on the list, you are welcome to test directly or try fine-tuning on your own data. We plan to expand language coverage in future releases.
Usage: This model is released under the Apache-2.0 license. For production deployments, we recommend conducting thorough testing and safety evaluation tailored to your use case.

📖 Citation

If you find VoxCPM helpful, please consider citing our work and starring ⭐ the repository!

@article{voxcpm2_2026,
  title   = {VoxCPM2: Tokenizer-Free TTS for Multilingual Speech Generation, Creative Voice Design, and True-to-Life Cloning},
  author  = {VoxCPM Team},
  journal = {GitHub},
  year    = {2026},
}

@article{voxcpm2025,
  title   = {VoxCPM: Tokenizer-Free TTS for Context-Aware Speech Generation
             and True-to-Life Voice Cloning},
  author  = {Zhou, Yixuan and Zeng, Guoyang and Liu, Xin and Li, Xiang and
             Yu, Renjie and Wang, Ziyang and Ye, Runchuan and Sun, Weiyue and
             Gui, Jiancheng and Li, Kehan and Wu, Zhiyong and Liu, Zhiyuan},
  journal = {arXiv preprint arXiv:2509.24650},
  year    = {2025},
}

📄 License

VoxCPM model weights and code are open-sourced under the Apache-2.0 license.

🙏 Acknowledgments

DiTAR for the diffusion autoregressive backbone
MiniCPM-4 for the language model foundation
CosyVoice for the Flow Matching-based LocDiT implementation
DAC for the Audio VAE backbone
Our community users for trying VoxCPM, reporting issues, sharing ideas, and contributing—your support helps the project keep getting better

Institutions

ModelBest THUHCSI

⭐ Star History

obra/superpowers

An agentic skills framework & software development methodology that works.

Superpowers

Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.

How it works

It starts from the moment you fire up your coding agent. As soon as it sees that you're building something, it doesn't just jump into trying to write code. Instead, it steps back and asks you what you're really trying to do.

Once it's teased a spec out of the conversation, it shows it to you in chunks short enough to actually read and digest.

After you've signed off on the design, your agent puts together an implementation plan that's clear enough for an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing to follow. It emphasizes true red/green TDD, YAGNI (You Aren't Gonna Need It), and DRY.

Next up, once you say "go", it launches a subagent-driven-development process, having agents work through each engineering task, inspecting and reviewing their work, and continuing forward. It's not uncommon for Claude to be able to work autonomously for a couple hours at a time without deviating from the plan you put together.

There's a bunch more to it, but that's the core of the system. And because the skills trigger automatically, you don't need to do anything special. Your coding agent just has Superpowers.

Sponsorship

If Superpowers has helped you do stuff that makes money and you are so inclined, I'd greatly appreciate it if you'd consider sponsoring my opensource work.

Thanks!

Jesse

Installation

Note: Installation differs by platform.

Claude Code Official Marketplace

Superpowers is available via the official Claude plugin marketplace

Install the plugin from Anthropic's official marketplace:

/plugin install superpowers@claude-plugins-official

Claude Code (Superpowers Marketplace)

The Superpowers marketplace provides Superpowers and some other related plugins for Claude Code.

In Claude Code, register the marketplace first:

/plugin marketplace add obra/superpowers-marketplace

Then install the plugin from this marketplace:

/plugin install superpowers@superpowers-marketplace

OpenAI Codex CLI

Open plugin search interface

/plugins

Search for Superpowers

superpowers

Select Install Plugin

OpenAI Codex App

In the Codex app, click on Plugins in the sidebar.
You should see Superpowers in the Coding section.
Click the + next to Superpowers and follow the prompts.

Cursor (via Plugin Marketplace)

In Cursor Agent chat, install from marketplace:

/add-plugin superpowers

or search for "superpowers" in the plugin marketplace.

OpenCode

Tell OpenCode:

Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md

Detailed docs: docs/README.opencode.md

GitHub Copilot CLI

copilot plugin marketplace add obra/superpowers-marketplace
copilot plugin install superpowers@superpowers-marketplace

Gemini CLI

gemini extensions install https://github.com/obra/superpowers

To update:

gemini extensions update superpowers

The Basic Workflow

brainstorming - Activates before writing code. Refines rough ideas through questions, explores alternatives, presents design in sections for validation. Saves design document.
using-git-worktrees - Activates after design approval. Creates isolated workspace on new branch, runs project setup, verifies clean test baseline.
writing-plans - Activates with approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task has exact file paths, complete code, verification steps.
subagent-driven-development or executing-plans - Activates with plan. Dispatches fresh subagent per task with two-stage review (spec compliance, then code quality), or executes in batches with human checkpoints.
test-driven-development - Activates during implementation. Enforces RED-GREEN-REFACTOR: write failing test, watch it fail, write minimal code, watch it pass, commit. Deletes code written before tests.
requesting-code-review - Activates between tasks. Reviews against plan, reports issues by severity. Critical issues block progress.
finishing-a-development-branch - Activates when tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

The agent checks for relevant skills before any task. Mandatory workflows, not suggestions.

What's Inside

Skills Library

Testing

test-driven-development - RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging

systematic-debugging - 4-phase root cause process (includes root-cause-tracing, defense-in-depth, condition-based-waiting techniques)
verification-before-completion - Ensure it's actually fixed

Collaboration

brainstorming - Socratic design refinement
writing-plans - Detailed implementation plans
executing-plans - Batch execution with checkpoints
dispatching-parallel-agents - Concurrent subagent workflows
requesting-code-review - Pre-review checklist
receiving-code-review - Responding to feedback
using-git-worktrees - Parallel development branches
finishing-a-development-branch - Merge/PR decision workflow
subagent-driven-development - Fast iteration with two-stage review (spec compliance, then code quality)

Meta

writing-skills - Create new skills following best practices (includes testing methodology)
using-superpowers - Introduction to the skills system

Philosophy

Test-Driven Development - Write tests first, always
Systematic over ad-hoc - Process over guessing
Complexity reduction - Simplicity as primary goal
Evidence over claims - Verify before declaring success

Read the original release announcement.

Contributing

The general contribution process for Superpowers is below. Keep in mind that we don't generally accept contributions of new skills and that any updates to skills must work across all of the coding agents we support.

Fork the repository
Switch to the 'dev' branch
Create a branch for your work
Follow the writing-skills skill for creating and testing new and modified skills
Submit a PR, being sure to fill in the pull request template.

See skills/writing-skills/SKILL.md for the complete guide.

Updating

Superpowers updates are somewhat coding-agent dependent, but are often automatic.

License

MIT License - see LICENSE file for details

Community

Superpowers is built by Jesse Vincent and the rest of the folks at Prime Radiant.

Discord: Join us for community support, questions, and sharing what you're building with Superpowers
Issues: https://github.com/obra/superpowers/issues
Release announcements: Sign up to get notified about new versions

HKUDS/DeepTutor

"DeepTutor: Agent-Native Personalized Learning Assistant"

DeepTutor: Agent-Native Personalized Tutoring

Features · Get Started · Explore · TutorBot · CLI · Community

🇨🇳 中文 · 🇯🇵 日本語 · 🇪🇸 Español · 🇫🇷 Français · 🇸🇦 العربية · 🇷🇺 Русский · 🇮🇳 हिन्दी · 🇵🇹 Português

📦 Releases

[2026.4.17] v1.1.1 — Universal "Answer now" escape hatch across every capability, Co-Writer resizable split with line-anchored scroll sync, Save-to-Notebook message-selection mode, real notebook system adoption across Knowledge/Guide/Save flows, unified collapsible settings panel, dedicated streaming Stop button, TutorBot config manager refactor with atomic writes, light/Snow theme refresh, and expanded test suite.

[2026.4.15] v1.1.0 — LaTeX block math parsing overhaul, LLM diagnostic probe agents.yaml configuration, extra headers forwarding in LLM factory, SaveToNotebookModal UUID fix, Docker + local LLM guidance, and expanded test suite.

[2026.4.14] v1.1.0-beta — URL-based chat routing with bookmarkable sessions, Snow theme, WebSocket heartbeat & auto-reconnect with resume, ChatComposer performance optimization, embedding provider registry overhaul, Serper search provider, streaming idle timeout, and expanded test suite.

[2026.4.13] v1.0.3 — Question Notebook for unified quiz review with bookmarks & categories, Mermaid diagram support in Visualize, embedding model mismatch detection, system message merging for Qwen/vLLM compatibility, LM Studio & llama.cpp provider support, and Glass theme.

[2026.4.11] v1.0.2 — Search consolidation simplification with SearXNG fallback, provider switch fix, explicit runtime config in test runner, and frontend resource leak fixes.

[2026.4.10] v1.0.1 — New Visualize capability with Chart.js/SVG rendering pipeline, quiz duplicate prevention with generation history, o4-mini model support, and server logging improvements.

[2026.4.10] v1.0.0-beta.4 — Embedding progress tracking with HTTP 429 rate limit retry, cross-platform start tour dependency management, and case-insensitive MIME validation fix.

[2026.4.8] v1.0.0-beta.3 — Remove litellm dependency with native OpenAI/Anthropic SDK providers, Windows Math Animator compatibility, robust JSON parsing for LLM outputs, Guided Learning KaTeX & navigation fixes, and full i18n coverage for Chinese.

[2026.4.7] v1.0.0-beta.2 — Runtime cache invalidation for hot settings reload, MinerU nested output support, mimic WebSocket fix, Python 3.11+ minimum, and CI improvements.

[2026.4.4] v1.0.0-beta.1 — Agent-native architecture rewrite (～200k lines) with two-layer plugin model (Tools + Capabilities), CLI & SDK entry points, TutorBot multi-channel bot agent, Co-Writer, Guided Learning, and persistent memory.

Past releases

[2026.1.23] v0.6.0 — Session persistence, incremental document upload, flexible RAG pipeline import, and full Chinese localization.

[2026.1.18] v0.5.2 — Docling support for RAG-Anything, logging system optimization, and bug fixes.

[2026.1.15] v0.5.0 — Unified service configuration, RAG pipeline selection per knowledge base, question generation overhaul, and sidebar customization.

[2026.1.9] v0.4.0 — Multi-provider LLM & embedding support, new home page, RAG module decoupling, and environment variable refactor.

[2026.1.5] v0.3.0 — Unified PromptManager architecture, GitHub Actions CI/CD, and pre-built Docker images on GHCR.

[2026.1.2] v0.2.0 — Docker deployment, Next.js 16 & React 19 upgrade, WebSocket security hardening, and critical vulnerability fixes.

📰 News

[2026.4.4] Long time no see! ✨ DeepTutor v1.0.0 is finally here — an agent-native evolution featuring a ground-up architecture rewrite, TutorBot, and flexible mode switching under the Apache-2.0 license. A new chapter begins, and our story continues!

[2026.2.6] 🚀 We've reached 10k stars in just 39 days! A huge thank you to our incredible community for the support!

[2026.1.1] Happy New Year! Join our Discord, WeChat, or Discussions — let's shape the future of DeepTutor together!

[2025.12.29] DeepTutor is officially released!

✨ Key Features

Unified Chat Workspace — Five modes, one thread. Chat, Deep Solve, Quiz Generation, Deep Research, and Math Animator share the same context — start a conversation, escalate to multi-agent problem solving, generate quizzes, then deep-dive into research, all without losing a single message.
Personal TutorBots — Not chatbots — autonomous tutors. Each TutorBot lives in its own workspace with its own memory, personality, and skill set. They set reminders, learn new abilities, and evolve as you grow. Powered by nanobot.
AI Co-Writer — A Markdown editor where AI is a first-class collaborator. Select text, rewrite, expand, or summarize — drawing from your knowledge base and the web. Every piece feeds back into your learning ecosystem.
Guided Learning — Turn your materials into structured, visual learning journeys. DeepTutor designs multi-step plans, generates interactive pages for each knowledge point, and lets you discuss alongside each step.
Knowledge Hub — Upload PDFs, Markdown, and text files to build RAG-ready knowledge bases. Organize insights across sessions in color-coded notebooks. Your documents don't just sit there — they actively power every conversation.
Persistent Memory — DeepTutor builds a living profile of you: what you've studied, how you learn, and where you're heading. Shared across all features and TutorBots, it gets sharper with every interaction.
Agent-Native CLI — Every capability, knowledge base, session, and TutorBot is one command away. Rich terminal output for humans, structured JSON for AI agents and pipelines. Hand DeepTutor a SKILL.md and your agents can operate it autonomously.

🚀 Get Started

Option A — Setup Tour (Recommended)

A single interactive script that walks you through everything: dependency installation, environment configuration, live connection testing, and launch. No manual .env editing needed.

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

# Create a Python environment
conda create -n deeptutor python=3.11 && conda activate deeptutor
# Or: python -m venv .venv && source .venv/bin/activate

# Launch the guided tour
python scripts/start_tour.py

The tour asks how you'd like to use DeepTutor:

Web mode (recommended) — Picks a dependency profile, installs everything (pip + npm), then spins up a temporary server and opens the Settings page in your browser. A four-step guided tour walks you through LLM, Embedding, and Search provider setup with live connection testing. Once complete, DeepTutor restarts automatically with your configuration.
CLI mode — A fully interactive terminal flow: choose a dependency profile, install dependencies, configure providers, verify connections, and apply — all without leaving the shell.

Either way, you end up with a running DeepTutor at http://localhost:3782.

Option B — Manual Local Install

If you prefer full control, install and configure everything yourself.

1. Install dependencies

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor

conda create -n deeptutor python=3.11 && conda activate deeptutor
pip install -e ".[server]"

# Frontend
cd web && npm install && cd ..

2. Configure environment

cp .env.example .env

Edit .env and fill in at least the required fields:

# LLM (Required)
LLM_BINDING=openai
LLM_MODEL=gpt-4o-mini
LLM_API_KEY=sk-xxx
LLM_HOST=https://api.openai.com/v1

# Embedding (Required for Knowledge Base)
EMBEDDING_BINDING=openai
EMBEDDING_MODEL=text-embedding-3-large
EMBEDDING_API_KEY=sk-xxx
EMBEDDING_HOST=https://api.openai.com/v1
EMBEDDING_DIMENSION=3072

Supported LLM Providers

Provider	Binding	Default Base URL
AiHubMix	`aihubmix`	`https://aihubmix.com/v1`
Anthropic	`anthropic`	`https://api.anthropic.com/v1`
Azure OpenAI	`azure_openai`	—
BytePlus	`byteplus`	`https://ark.ap-southeast.bytepluses.com/api/v3`
BytePlus Coding Plan	`byteplus_coding_plan`	`https://ark.ap-southeast.bytepluses.com/api/coding/v3`
Custom (OpenAI-compat)	`custom`	—
DashScope (Qwen)	`dashscope`	`https://dashscope.aliyuncs.com/compatible-mode/v1`
DeepSeek	`deepseek`	`https://api.deepseek.com`
Gemini	`gemini`	`https://generativelanguage.googleapis.com/v1beta/openai/`
GitHub Copilot	`github_copilot`	`https://api.githubcopilot.com`
Groq	`groq`	`https://api.groq.com/openai/v1`
llama.cpp	`llama_cpp`	`http://localhost:8080/v1`
LM Studio	`lm_studio`	`http://localhost:1234/v1`
MiniMax	`minimax`	`https://api.minimax.io/v1`
Mistral	`mistral`	`https://api.mistral.ai/v1`
Moonshot (Kimi)	`moonshot`	`https://api.moonshot.ai/v1`
Ollama	`ollama`	`http://localhost:11434/v1`
OpenAI	`openai`	`https://api.openai.com/v1`
OpenAI Codex	`openai_codex`	`https://chatgpt.com/backend-api`
OpenRouter	`openrouter`	`https://openrouter.ai/api/v1`
OpenVINO Model Server	`ovms`	`http://localhost:8000/v3`
Qianfan (Ernie)	`qianfan`	`https://qianfan.baidubce.com/v2`
SiliconFlow	`siliconflow`	`https://api.siliconflow.cn/v1`
Step Fun	`stepfun`	`https://api.stepfun.com/v1`
vLLM	`vllm`	`http://localhost:8000/v1`
VolcEngine	`volcengine`	`https://ark.cn-beijing.volces.com/api/v3`
VolcEngine Coding Plan	`volcengine_coding_plan`	`https://ark.cn-beijing.volces.com/api/coding/v3`
Xiaomi MIMO	`xiaomi_mimo`	`https://api.xiaomimimo.com/v1`
Zhipu AI (GLM)	`zhipu`	`https://open.bigmodel.cn/api/paas/v4`

Supported Embedding Providers

Provider	Binding	Model Example	Default Dim
OpenAI	`openai`	`text-embedding-3-large`	3072
Azure OpenAI	`azure_openai`	deployment name	—
Cohere	`cohere`	`embed-v4.0`	1024
Jina	`jina`	`jina-embeddings-v3`	1024
Ollama	`ollama`	`nomic-embed-text`	768
vLLM / LM Studio	`vllm`	Any embedding model	—
Any OpenAI-compatible	`custom`	—	—

OpenAI-compatible providers (DashScope, SiliconFlow, etc.) work via the custom or openai binding.

Supported Web Search Providers

Provider	Env Key	Notes
Brave	`BRAVE_API_KEY`	Recommended, free tier available
Tavily	`TAVILY_API_KEY`
Jina	`JINA_API_KEY`
SearXNG	—	Self-hosted, no API key needed
DuckDuckGo	—	No API key needed
Perplexity	`PERPLEXITY_API_KEY`	Requires API key

3. Start services

# Backend (FastAPI)
python -m deeptutor.api.run_server

# Frontend (Next.js) — in a separate terminal
cd web && npm run dev -- -p 3782

Service	Default Port
Backend	`8001`
Frontend	`3782`

Open http://localhost:3782 and you're ready to go.

Option C — Docker Deployment

Docker wraps the backend and frontend into a single container — no local Python or Node.js required. Two options depending on your preference:

1. Configure environment variables (required for both options)

git clone https://github.com/HKUDS/DeepTutor.git
cd DeepTutor
cp .env.example .env

Edit .env and fill in at least the required fields (same as Option B above).

2a. Pull official image (recommended)

Official images are published to GitHub Container Registry on every release, built for linux/amd64 and linux/arm64.

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

To pin a specific version, edit the image tag in docker-compose.ghcr.yml:

image: ghcr.io/hkuds/deeptutor:1.0.0  # or :latest

2b. Build from source

docker compose up -d

This builds the image locally from Dockerfile and starts the container.

3. Verify & manage

Open http://localhost:3782 once the container is healthy.

docker compose logs -f   # tail logs
docker compose down       # stop and remove container

Cloud / remote server deployment

When deploying to a remote server, the browser needs to know the public URL of the backend API. Add one more variable to your .env:

# Set to the public URL where the backend is reachable
NEXT_PUBLIC_API_BASE_EXTERNAL=https://your-server.com:8001

The frontend startup script applies this value at runtime — no rebuild needed.

Development mode (hot-reload)

Layer the dev override to mount source code and enable hot-reload for both services:

docker compose -f docker-compose.yml -f docker-compose.dev.yml up

Changes to deeptutor/, deeptutor_cli/, scripts/, and web/ are reflected immediately.

Custom ports

Override the default ports in .env:

BACKEND_PORT=9001
FRONTEND_PORT=4000

Then restart:

docker compose up -d     # or docker compose -f docker-compose.ghcr.yml up -d

Data persistence

User data and knowledge bases are persisted via Docker volumes mapped to local directories:

Container path	Host path	Content
`/app/data/user`	`./data/user`	Settings, memory, workspace, sessions, logs
`/app/data/knowledge_bases`	`./data/knowledge_bases`	Uploaded documents & vector indices

These directories survive docker compose down and are reused on the next docker compose up.

Environment variables reference

Variable	Required	Description
`LLM_BINDING`	Yes	LLM provider (`openai`, `anthropic`, etc.)
`LLM_MODEL`	Yes	Model name (e.g. `gpt-4o`)
`LLM_API_KEY`	Yes	Your LLM API key
`LLM_HOST`	Yes	API endpoint URL
`EMBEDDING_BINDING`	Yes	Embedding provider
`EMBEDDING_MODEL`	Yes	Embedding model name
`EMBEDDING_API_KEY`	Yes	Embedding API key
`EMBEDDING_HOST`	Yes	Embedding endpoint
`EMBEDDING_DIMENSION`	Yes	Vector dimension
`SEARCH_PROVIDER`	No	Search provider (`tavily`, `jina`, `serper`, `perplexity`, etc.)
`SEARCH_API_KEY`	No	Search API key
`BACKEND_PORT`	No	Backend port (default `8001`)
`FRONTEND_PORT`	No	Frontend port (default `3782`)
`NEXT_PUBLIC_API_BASE_EXTERNAL`	No	Public backend URL for cloud deployment
`DISABLE_SSL_VERIFY`	No	Disable SSL verification (default `false`)

Option D — CLI Only

If you just want the CLI without the web frontend:

pip install -e ".[cli]"
deeptutor chat                                   # Interactive REPL
deeptutor run chat "Explain Fourier transform"   # One-shot capability
deeptutor run deep_solve "Solve x^2 = 4"         # Multi-agent problem solving
deeptutor kb create my-kb --doc textbook.pdf     # Build a knowledge base

See DeepTutor CLI for the full feature guide and command reference.

📖 Explore DeepTutor

💬 Chat — Unified Intelligent Workspace

Five distinct modes coexist in a single workspace, bound by a unified context management system. Conversation history, knowledge bases, and references persist across modes — switch between them freely within the same topic, whenever the moment calls for it.

Mode	What It Does
Chat	Fluid, tool-augmented conversation. Choose from RAG retrieval, web search, code execution, deep reasoning, brainstorming, and paper search — mix and match as needed.
Deep Solve	Multi-agent problem solving: plan, investigate, solve, and verify — with precise source citations at every step.
Quiz Generation	Generate assessments grounded in your knowledge base, with built-in validation.
Deep Research	Decompose a topic into subtopics, dispatch parallel research agents across RAG, web, and academic papers, and produce a fully cited report.
Math Animator	Turn mathematical concepts into visual animations and storyboards powered by Manim.

Tools are decoupled from workflows — in every mode, you decide which tools to enable, how many to use, or whether to use any at all. The workflow orchestrates the reasoning; the tools are yours to compose.

Start with a quick chat question, escalate to Deep Solve when it gets hard, generate quiz questions to test yourself, then launch a Deep Research to go deeper — all in one continuous thread.

✍️ Co-Writer — AI Inside Your Editor

Co-Writer brings the intelligence of Chat directly into a writing surface. It is a full-featured Markdown editor where AI is a first-class collaborator — not a sidebar, not an afterthought.

Select any text and choose Rewrite, Expand, or Shorten — optionally drawing context from your knowledge base or the web. The editing flow is non-destructive with full undo/redo, and every piece you write can be saved straight to your notebooks, feeding back into your learning ecosystem.

🎓 Guided Learning — Visual, Step-by-Step Mastery

Guided Learning turns your personal materials into structured, multi-step learning journeys. Provide a topic, optionally link notebook records, and DeepTutor will:

Design a learning plan — Identify 3–5 progressive knowledge points from your materials.
Generate interactive pages — Each point becomes a rich visual HTML page with explanations, diagrams, and examples.
Enable contextual Q&A — Chat alongside each step for deeper exploration.
Summarize your progress — Upon completion, receive a learning summary of everything you've covered.

Sessions are persistent — pause, resume, or revisit any step at any time.

📚 Knowledge Management — Your Learning Infrastructure

Knowledge is where you build and manage the document collections that power everything else in DeepTutor.

Knowledge Bases — Upload PDF, TXT, or Markdown files to create searchable, RAG-ready collections. Add documents incrementally as your library grows.
Notebooks — Organize learning records across sessions. Save insights from Chat, Guided Learning, Co-Writer, or Deep Research into categorized, color-coded notebooks.

Your knowledge base is not passive storage — it actively participates in every conversation, every research session, and every learning path you create.

🧠 Memory — DeepTutor Learns As You Learn

DeepTutor maintains a persistent, evolving understanding of you through two complementary dimensions:

Summary — A running digest of your learning progress: what you've studied, which topics you've explored, and how your understanding has developed.
Profile — Your learner identity: preferences, knowledge level, goals, and communication style — automatically refined through every interaction.

Memory is shared across all features and all your TutorBots. The more you use DeepTutor, the more personalized and effective it becomes.

🦞 TutorBot — Persistent, Autonomous AI Tutors

TutorBot is not a chatbot — it is a persistent, multi-instance agent built on nanobot. Each TutorBot runs its own agent loop with independent workspace, memory, and personality. Create a Socratic math tutor, a patient writing coach, and a rigorous research advisor — all running simultaneously, each evolving with you.

Soul Templates — Define your tutor's personality, tone, and teaching philosophy through editable Soul files. Choose from built-in archetypes (Socratic, encouraging, rigorous) or craft your own — the soul shapes every response.
Independent Workspace — Each bot has its own directory with separate memory, sessions, skills, and configuration — fully isolated yet able to access DeepTutor's shared knowledge layer.
Proactive Heartbeat — Bots don't just respond — they initiate. The built-in Heartbeat system enables recurring study check-ins, review reminders, and scheduled tasks. Your tutor shows up even when you don't.
Full Tool Access — Every bot reaches into DeepTutor's complete toolkit: RAG retrieval, code execution, web search, academic paper search, deep reasoning, and brainstorming.
Skill Learning — Teach your bot new abilities by adding skill files to its workspace. As your needs evolve, so does your tutor's capability.
Multi-Channel Presence — Connect bots to Telegram, Discord, Slack, Feishu, WeChat Work, DingTalk, Email, and more. Your tutor meets you wherever you are.
Team & Sub-Agents — Spawn background sub-agents or orchestrate multi-agent teams within a single bot for complex, long-running tasks.

deeptutor bot create math-tutor --persona "Socratic math teacher who uses probing questions"
deeptutor bot create writing-coach --persona "Patient, detail-oriented writing mentor"
deeptutor bot list                  # See all your active tutors

⌨️ DeepTutor CLI — Agent-Native Interface

DeepTutor is fully CLI-native. Every capability, knowledge base, session, memory, and TutorBot is one command away — no browser required. The CLI serves both humans (with rich terminal rendering) and AI agents (with structured JSON output).

Hand the SKILL.md at the project root to any tool-using agent (nanobot, or any LLM with tool access), and it can configure and operate DeepTutor autonomously.

One-shot execution — Run any capability directly from the terminal:

deeptutor run chat "Explain the Fourier transform" -t rag --kb textbook
deeptutor run deep_solve "Prove that √2 is irrational" -t reason
deeptutor run deep_question "Linear algebra" --config num_questions=5
deeptutor run deep_research "Attention mechanisms in transformers"

Interactive REPL — A persistent chat session with live mode switching:

deeptutor chat --capability deep_solve --kb my-kb
# Inside the REPL: /cap, /tool, /kb, /history, /notebook, /config to switch on the fly

Knowledge base lifecycle — Build, query, and manage RAG-ready collections entirely from the terminal:

deeptutor kb create my-kb --doc textbook.pdf       # Create from document
deeptutor kb add my-kb --docs-dir ./papers/         # Add a folder of papers
deeptutor kb search my-kb "gradient descent"        # Search directly
deeptutor kb set-default my-kb                      # Set as default for all commands

Dual output mode — Rich rendering for humans, structured JSON for pipelines:

deeptutor run chat "Summarize chapter 3" -f rich    # Colored, formatted output
deeptutor run chat "Summarize chapter 3" -f json    # Line-delimited JSON events

Session continuity — Resume any conversation right where you left off:

deeptutor session list                              # List all sessions
deeptutor session open <id>                         # Resume in REPL

Full CLI command reference

Top-level

Command	Description
`deeptutor run <capability> <message>`	Run any capability in a single turn (`chat`, `deep_solve`, `deep_question`, `deep_research`, `math_animator`)
`deeptutor chat`	Interactive REPL with optional `--capability`, `--tool`, `--kb`, `--language`
`deeptutor serve`	Start the DeepTutor API server

deeptutor bot

Command	Description
`deeptutor bot list`	List all TutorBot instances
`deeptutor bot create <id>`	Create and start a new bot (`--name`, `--persona`, `--model`)
`deeptutor bot start <id>`	Start a bot
`deeptutor bot stop <id>`	Stop a bot

deeptutor kb

Command	Description
`deeptutor kb list`	List all knowledge bases
`deeptutor kb info <name>`	Show knowledge base details
`deeptutor kb create <name>`	Create from documents (`--doc`, `--docs-dir`)
`deeptutor kb add <name>`	Add documents incrementally
`deeptutor kb search <name> <query>`	Search a knowledge base
`deeptutor kb set-default <name>`	Set as default KB
`deeptutor kb delete <name>`	Delete a knowledge base (`--force`)

deeptutor memory

Command	Description
`deeptutor memory show [file]`	View memory (`summary`, `profile`, or `all`)
`deeptutor memory clear [file]`	Clear memory (`--force`)

deeptutor session

Command	Description
`deeptutor session list`	List sessions (`--limit`)
`deeptutor session show <id>`	View session messages
`deeptutor session open <id>`	Resume session in REPL
`deeptutor session rename <id>`	Rename a session (`--title`)
`deeptutor session delete <id>`	Delete a session

deeptutor notebook

Command	Description
`deeptutor notebook list`	List notebooks
`deeptutor notebook create <name>`	Create a notebook (`--description`)
`deeptutor notebook show <id>`	View notebook records
`deeptutor notebook add-md <id> <path>`	Import markdown as record
`deeptutor notebook replace-md <id> <rec> <path>`	Replace a markdown record
`deeptutor notebook remove-record <id> <rec>`	Remove a record

deeptutor config / plugin / provider

Command	Description
`deeptutor config show`	Print current configuration summary
`deeptutor plugin list`	List registered tools and capabilities
`deeptutor plugin info <name>`	Show tool or capability details
`deeptutor provider login <provider>`	Provider auth (`openai-codex` OAuth login; `github-copilot` validates an existing Copilot auth session)

🗺️ Roadmap

Status	Milestone
🎯	Authentication & Login — Optional login page for public deployments with multi-user support
🎯	Themes & Appearance — Diverse theme options and customizable UI appearance
🎯	Interaction Improvement — optimize icon design and interaction details
🔜	Better Memories — integrating better memory management
🔜	LightRAG Integration — Integrate LightRAG as an advanced knowledge base engine
🔜	Documentation Site — Comprehensive docs page with guides, API reference, and tutorials

If you find DeepTutor useful, give us a star — it helps us keep going!

🌐 Community & Ecosystem

DeepTutor stands on the shoulders of outstanding open-source projects:

Project	Role in DeepTutor
nanobot	Ultra-lightweight agent engine powering TutorBot
LlamaIndex	RAG pipeline and document indexing backbone
ManimCat	AI-driven math animation generation for Math Animator

From the HKUDS ecosystem:

⚡ LightRAG	🤖 AutoAgent	🔬 AI-Researcher	🧬 nanobot
Simple & Fast RAG	Zero-Code Agent Framework	Automated Research	Ultra-Lightweight AI Agent

🤝 Contributing

We hope DeepTutor becomes a gift for the community. 🎁

See CONTRIBUTING.md for guidelines on setting up your development environment, code standards, and pull request workflow.

⭐ Star History

Data Intelligence Lab @ HKU

⭐ Star us · 🐛 Report a bug · 💬 Discussions

Licensed under the Apache License 2.0.

onyx-dot-app/onyx

Open Source AI Platform - AI Chat with advanced features that works with every LLM

Onyx - The Open Source AI Platform

Onyx is the application layer for LLMs - bringing a feature-rich interface that can be easily hosted by anyone. Onyx enables LLMs through advanced capabilities like RAG, web search, code execution, file creation, deep research and more.

Connect your applications with over 50+ indexing based connectors provided out of the box or via MCP.

Tip

Deploy with a single command:

curl -fsSL https://onyx.app/install_onyx.sh | bash

⭐ Features

🔍 Agentic RAG: Get best in class search and answer quality based on hybrid index + AI Agents for information retrieval
- Benchmark to release soon!
🔬 Deep Research: Get in depth reports with a multi-step research flow.
- Top of leaderboard as of Feb 2026.
🤖 Custom Agents: Build AI Agents with unique instructions, knowledge, and actions.
🌍 Web Search: Browse the web to get up to date information.
- Supports Serper, Google PSE, Brave, SearXNG, and others.
- Comes with an in house web crawler and support for Firecrawl/Exa.
📄 Artifacts: Generate documents, graphics, and other downloadable artifacts.
▶️ Actions & MCP: Let Onyx agents interact with external applications, comes with flexible Auth options.
💻 Code Execution: Execute code in a sandbox to analyze data, render graphs, or modify files.
🎙️ Voice Mode: Chat with Onyx via text-to-speech and speech-to-text.
🎨 Image Generation: Generate images based on user prompts.

Onyx supports all major LLM providers, both self-hosted (like Ollama, LiteLLM, vLLM, etc.) and proprietary (like Anthropic, OpenAI, Gemini, etc.).

To learn more - check out our docs!

🚀 Deployment Modes

Onyx supports deployments in Docker, Kubernetes, Helm/Terraform and provides guides for major cloud providers. Detailed deployment guides found here.

Onyx supports two separate deployment options: standard and lite.

Onyx Lite

The Lite mode can be thought of as a lightweight Chat UI. It requires less resources (under 1GB memory) and runs a less complex stack. It is great for users who want to test out Onyx quickly or for teams who are only interested in the Chat UI and Agents functionalities.

Standard Onyx

The complete feature set of Onyx which is recommended for serious users and larger teams. Additional components not included in Lite mode:

Vector + Keyword index for RAG.
Background containers to run job queues and workers for syncing knowledge from connectors.
AI model inference servers to run deep learning models used during indexing and inference.
Performance optimizations for large scale use via in memory cache (Redis) and blob store (MinIO).

Tip

To try Onyx for free without deploying, visit Onyx Cloud.

🏢 Onyx for Enterprise

Onyx is built for teams of all sizes, from individual users to the largest global enterprises:

👥 Collaboration: Share chats and agents with other members of your organization.
🔐 Single Sign On: SSO via Google OAuth, OIDC, or SAML. Group syncing and user provisioning via SCIM.
🛡️ Role Based Access Control: RBAC for sensitive resources like access to agents, actions, etc.
📊 Analytics: Usage graphs broken down by teams, LLMs, or agents.
🕵️ Query History: Audit usage to ensure safe adoption of AI in your organization.
💻 Custom code: Run custom code to remove PII, reject sensitive queries, or to run custom analysis.
🎨 Whitelabeling: Customize the look and feel of Onyx with custom naming, icons, banners, and more.

📚 Licensing

There are two editions of Onyx:

Onyx Community Edition (CE) is available freely under the MIT license and covers all of the core features for Chat, RAG, Agents, and Actions.
Onyx Enterprise Edition (EE) includes extra features that are primarily useful for larger organizations.

For feature details, check out our website.

👪 Community

Join our open source community on Discord!

💡 Contributing

Looking to contribute? Please check out the Contribution Guide for more details.

GitHub All Languages Monthly Trending

NousResearch/hermes-agent

Hermes Agent ☤

Quick Install

Getting Started

CLI vs Messaging Quick Reference

Documentation

Migrating from OpenClaw

Contributing

Community

License

forrestchang/andrej-karpathy-skills

Karpathy-Inspired Claude Code Guidelines

The Problems

The Solution

The Four Principles in Detail

1. Think Before Coding

2. Simplicity First

3. Surgical Changes

4. Goal-Driven Execution

Install

Key Insight

How to Know It's Working

Customization

Tradeoff Note

License

Crosstalk-Solutions/project-nomad

Project N.O.M.A.D.

Node for Offline Media, Archives, and Data

Installation & Quickstart

Quick Install (Debian-based OS Only)

Advanced Installation

How It Works

What's Included

Device Requirements

Minimum Specs

Optimal Specs

Running AI models on a different host

Frequently Asked Questions (FAQ)

About Internet Usage & Privacy

About Security

Contributing

Community & Resources

License

Helper Scripts

Start Script - Starts all installed project containers

Stop Script - Stops all installed project containers

Uninstall Script - Need to start fresh? Use the uninstall script to make your life easy. Note: this cannot be undone!

bytedance/deer-flow

🦌 DeerFlow - 2.0

Official Website

Coding Plan from ByteDance Volcengine

InfoQuest

Table of Contents

One-Line Agent Setup

Quick Start

Configuration

Running the Application

Deployment Sizing

Option 1: Docker (Recommended)

Option 2: Local Development

Startup Modes

Why Gateway Mode?

Docker Production Deployment

Advanced

Sandbox Mode

MCP Server

IM Channels

LangSmith Tracing

Langfuse Tracing

Using Both Providers

From Deep Research to Super Agent Harness

Core Features

Skills & Tools

Claude Code Integration

Sub-Agents

Sandbox & File System

Context Engineering

Long-Term Memory

Recommended Models