StealthOS

The stealth-mode AI Operating System for any IDE. One command. Works in Claude Code, Cursor, Antigravity, Windsurf, Cline, Continue, Copilot, TRAE / TRAE SOLO, VSCode, Codex/Aider, ChatGPT.

v1.1.0-beta.2 — Onboarding Experience & Diagnostics. 82 MCP tools. 5-phase cognitive architecture: features → memory compiler → context router → persistent agents → semantic build system.

Install in 1 command

npx create-stealthos@beta

The scaffolder will:

Ask which IDEs you use (Claude Code + Antigravity pre-selected).
Auto-install ~/.stealthos/ if missing (knowledge base + MCP server + deps).
Drop IDE stubs in your project — including MCP connection config wired to your stealthos home.
Print next steps.

Important — restart your IDE after the scaffolder finishes. MCP servers are only connected when the IDE process boots; opening a new tab is not enough.

The 3 commands

Command	What it does
`/init`	Progressive discovery: 5 critical questions → blueprint recommendation (9 templates: web, saas, crm, mobile, game, realtime, telemetry, ai-platform) → apply blueprint scaffolding → 6 complementary questions → snapshot. Run once per project.
`/sync`	Re-analyze, lint, rebuild context, snapshot, and compile `runtime/full-context.md` — a single markdown file sized to your LLM's context window. Run after each development block (or let `/work` do it automatically).
`/work`	Intent-driven pipeline: classify task → load `full-context.md` → ask clarifications → propose plan → wait for approval → execute → log → auto-trigger `/sync`. The chain `/init → /sync → /work → auto-sync → /work …` keeps state fresh without manual discipline.

Claude Code: native slash commands. Antigravity: native workflows in .agents/workflows/. Cursor / Cline / Continue / Windsurf / TRAE SOLO: natural language ("inicialize o projeto", "sincronize", "trabalhe nesta task") — the MCP tool aios_run_workflow is invoked transparently. VSCode (sem extensão de agente): Ctrl+Shift+P → Run Task → StealthOS: /init etc., powered by npx stealthos-cli@beta run <workflow>. Não há /init no chat porque VSCode core não tem chat de agente — para isso, instale Cline, Continue.dev ou Copilot Chat e selecione no scaffolder.

Importante sobre slash commands: /init, /sync, /work no chat só funcionam em IDEs com agente de chat nativo (Claude Code, Antigravity). Em IDEs com extensões de agente (Cursor, Cline, Continue, TRAE), use linguagem natural — o agente chama a tool MCP aios_run_workflow transparentemente. Em VSCode puro, use Tasks (Ctrl+Shift+P).

MCP connection — how it works

StealthOS exposes 82 tools over MCP stdio from ~/.stealthos/server/aios-server.mjs. Every IDE that supports MCP can connect.

Tool families:

Base (56): core bundle, routing, classification, memory, lint, detect-stack, blueprint, workflow engine, full-context compiler, doctor/repair, network diagnostics, memory GC
Phase 1 — Cognitive Features (4): aios_feature_list, aios_feature_manifest, aios_feature_memory_compile, aios_feature_compile_all
Phase 2 — Memory Compiler (3): aios_feature_create, aios_feature_pipeline_run, aios_feature_pipeline_all (L1→L2→L3→L4 deterministic transformations)
Phase 3 — Context Router (4): aios_context_route, aios_context_pack, aios_context_pack_save, aios_context_pack_list
Phase 4 — Persistent Agents (10): aios_agent_* (list/create/get/state/message/inbox/execute/complete) + aios_orchestrator_decompose
Phase 5 — Semantic Build System (5): aios_build_graph, aios_build_status, aios_build_run, aios_build_list, aios_build_rollback

The scaffolder writes the correct config for each IDE you pick. If you ever need to configure manually (custom setup, troubleshooting, IDEs not yet supported), use the snippets below.

Generic MCP server entry

{
  "command": "node",
  "args": ["<HOME>/.stealthos/server/aios-server.mjs"],
  "env": {
    "STEALTHOS_MODE": "hybrid",
    "STEALTHOS_HOME": "<HOME>/.stealthos",
    "STEALTHOS_PROJECT_DIR": "<project-dir-token>"
  }
}

Replace <HOME> with C:\Users\<you> on Windows or /home/<you> (or /Users/<you> on macOS) on Unix. <project-dir-token> is the IDE-specific variable that expands to the current project root at runtime — see the IDE-specific section below.

Per-IDE config

Claude Code

File: .claude/settings.json (project-scoped) or ~/.claude/settings.json (global).

Project-dir token: ${CLAUDE_PROJECT_DIR}

{
  "mcpServers": {
    "ai-os": {
      "command": "node",
      "args": ["C:\\Users\\<you>\\.stealthos\\server\\aios-server.mjs"],
      "env": {
        "STEALTHOS_MODE": "hybrid",
        "STEALTHOS_HOME": "C:\\Users\\<you>\\.stealthos",
        "STEALTHOS_PROJECT_DIR": "${CLAUDE_PROJECT_DIR}"
      }
    }
  },
  "hooks": {
    "UserPromptSubmit": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"C:\\Users\\<you>\\.stealthos\\hooks\\inject-os-reminder.ps1\"" }
      ] }
    ],
    "PreToolUse": [
      { "matcher": "Edit|Write|NotebookEdit|Bash", "hooks": [
        { "type": "command", "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"C:\\Users\\<you>\\.stealthos\\hooks\\guard-edit.ps1\"" }
      ] }
    ],
    "Stop": [
      { "matcher": "*", "hooks": [
        { "type": "command", "command": "powershell -NoProfile -ExecutionPolicy Bypass -File \"C:\\Users\\<you>\\.stealthos\\hooks\\enforce-audit.ps1\"" }
      ] }
    ]
  }
}

Linux/macOS: replace the powershell commands with bash "<HOME>/.stealthos/hooks/inject-os-reminder.sh" (same name with .sh extension).

Slash commands /init, /sync, /work come from .claude/commands/*.md (auto-installed by the scaffolder).

Antigravity

File: .gemini/settings.json (project-scoped).

Project-dir token: ${PWD}

{
  "mcpServers": {
    "ai-os": {
      "command": "node",
      "args": ["<HOME>/.stealthos/server/aios-server.mjs"],
      "env": {
        "STEALTHOS_MODE": "hybrid",
        "STEALTHOS_HOME": "<HOME>/.stealthos",
        "STEALTHOS_PROJECT_DIR": "${PWD}"
      }
    }
  }
}

Slash commands /init, /sync, /work come from .agents/workflows/*.md (auto-installed). Antigravity reads workflows on boot — restart the IDE after installing.

Reference: Antigravity docs — Rules & Workflows.

Cursor

File: .cursor/mcp.json (project-scoped) or ~/.cursor/mcp.json (global).

Project-dir token: ${workspaceFolder}

{
  "mcpServers": {
    "ai-os": {
      "command": "node",
      "args": ["<HOME>/.stealthos/server/aios-server.mjs"],
      "env": {
        "STEALTHOS_MODE": "hybrid",
        "STEALTHOS_HOME": "<HOME>/.stealthos",
        "STEALTHOS_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

Trigger commands by typing /mcp__ai-os__aios_run_workflow or by asking in natural language. .cursorrules (auto-installed) tells Cursor about the protocol.

Windsurf (Cascade)

File: ~/.codeium/windsurf/mcp_config.json (global — Windsurf doesn't yet support project-scoped MCP).

{
  "mcpServers": {
    "ai-os": {
      "command": "node",
      "args": ["<HOME>/.stealthos/server/aios-server.mjs"],
      "env": {
        "STEALTHOS_MODE": "hybrid",
        "STEALTHOS_HOME": "<HOME>/.stealthos"
      }
    }
  }
}

STEALTHOS_PROJECT_DIR is omitted because Windsurf doesn't pass a stable project-dir token; the server falls back to process.cwd(). Always launch Windsurf from the project root.

.windsurfrules (auto-installed) provides the protocol.

Cline (VSCode extension)

File: VSCode settings.json → cline.mcpServers block (global) or .vscode/cline.json (project).

{
  "cline.mcpServers": {
    "ai-os": {
      "command": "node",
      "args": ["<HOME>/.stealthos/server/aios-server.mjs"],
      "env": {
        "STEALTHOS_MODE": "hybrid",
        "STEALTHOS_HOME": "<HOME>/.stealthos",
        "STEALTHOS_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

.clinerules (auto-installed) tells Cline about the protocol. Use natural language to trigger workflows.

Continue.dev (VSCode / JetBrains)

File: .continue/config.yaml (project) or ~/.continue/config.yaml (global).

mcpServers:
  - name: ai-os
    command: node
    args:
      - <HOME>/.stealthos/server/aios-server.mjs
    env:
      STEALTHOS_MODE: hybrid
      STEALTHOS_HOME: <HOME>/.stealthos
      STEALTHOS_PROJECT_DIR: ${workspaceFolder}

.continue/rules/ai-os.md (auto-installed) describes the protocol.

TRAE / TRAE SOLO (ByteDance)

File: .trae/mcp.json (project-scoped — funciona em TRAE v1.3+ e TRAE SOLO v2.x).

Project-dir token: ${workspaceFolder}

{
  "mcpServers": {
    "ai-os": {
      "command": "node",
      "args": ["<HOME>/.stealthos/server/aios-server.mjs"],
      "env": {
        "STEALTHOS_MODE": "hybrid",
        "STEALTHOS_HOME": "<HOME>/.stealthos",
        "STEALTHOS_PROJECT_DIR": "${workspaceFolder}"
      }
    }
  }
}

O scaffolder cria .trae/mcp.json + .trae/rules/project_rules.md (rules auto-carregadas) e reescreve o path para apontar ao ~/.stealthos/server/ no modo hybrid. Após scaffold: reinicie a IDE e abra o painel MCP para confirmar conexão.

Slash commands (/init, /sync, /work) não existem em TRAE — use linguagem natural ("inicialize o projeto", "sincronize", "trabalhe nesta task: X"). O agente do TRAE invoca aios_run_workflow via MCP transparentemente.

Fallback sem MCP: npx -y stealthos-cli@beta run init no terminal integrado.

VSCode (sem extensão de agente)

VSCode core não tem chat de agente nem cliente MCP nativo — então /init, /sync, /work no chat não existem. O scaffolder fornece duas alternativas:

Tasks (Ctrl+Shift+P → Run Task):
- StealthOS: /init — chama npx -y stealthos-cli@beta run init
- StealthOS: /sync
- StealthOS: /work (pergunta o intent via input)
- StealthOS: status
Snippets (digite /init, /sync, /work em .md para expandir a um prompt que você cola em qualquer chat externo).

Para chat de agente nativo dentro do VSCode, instale uma extensão e selecione no scaffolder:

Cline (free, claude/gpt) — .clinerules + MCP global
Continue.dev (free, multi-LLM) — .continue/config.yaml (project-scoped MCP)
GitHub Copilot Chat (paid) — .github/copilot-instructions.md (sem MCP)

Pré-requisito das Tasks: Node ≥18 acessível via npx. Server vem de ~/.stealthos/server/ (instalado pelo scaffolder).

GitHub Copilot, ChatGPT, Codex/Aider

These clients don't speak MCP. The scaffolder drops a static instructions file:

Copilot → .github/copilot-instructions.md
ChatGPT (custom GPT) → GPT.md
Codex / Aider / Amp / Jules → AGENTS.md

They describe the protocol but can't call MCP tools. The user runs /init manually via npx stealthos-cli run init.

Troubleshooting MCP

"/init doesn't work / tools mcp__ai-os__* not in the picker"

Did you restart the IDE process completely after install? Closing a tab isn't enough.
Run npx stealthos-cli status — does ~/.stealthos/ exist?
Test the server directly:
```
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' | node "<HOME>/.stealthos/server/aios-server.mjs"
```
Should print JSON with 82 tools (1.1.0-beta.0+). If it errors, run cd ~/.stealthos/server && npm install.
Check your IDE's MCP log. Claude Code: ~/.claude/logs/. Cursor: Help → Toggle Developer Tools → Console.

"Hooks fail silently in Claude Code" Hook paths must point at ~/.stealthos/hooks/ (absolute), not ${CLAUDE_PROJECT_DIR}/.ai/hooks/ (which doesn't exist in hybrid mode). The scaffolder fixes this since alpha.6 — if you scaffolded earlier, re-run npx create-stealthos@beta --force.

"Antigravity slash commands don't show up" Workflows must live in .agents/workflows/<name>.md with YAML frontmatter (Antigravity format), not .gemini/commands/<name>.toml (Gemini CLI format). Fixed since alpha.7.

"create-stealthos says 'already scaffolded'" Use --force to overwrite: npx create-stealthos@beta --force.

Architecture

┌──────────────────────────────────────────────────────────┐
│  ~/.stealthos/                  ← installed ONCE          │
│  ├── server/aios-server.mjs     ← MCP daemon              │
│  ├── workflows/                 ← init.json, sync.json…   │
│  ├── hooks/                     ← inject/guard/enforce    │
│  ├── INDEX.md, CONTRACT.md      ← canonical knowledge     │
│  └── projects/                                            │
│      ├── 0064f1c50d48/          ← state of project A      │
│      └── 1aec0fc374b6/          ← state of project B      │
└──────────────────────────────────────────────────────────┘
       ▲                                       ▲
       │ MCP stdio                             │ MCP stdio
┌──────┴──────────────┐            ┌───────────┴──────────┐
│  ~/projects/A/      │            │  ~/projects/B/       │
│  ├── .stealthos.yml │            │  ├── .stealthos.yml  │
│  ├── CLAUDE.md      │            │  ├── CLAUDE.md       │
│  ├── .claude/       │            │  ├── .agents/        │
│  └── src/           │            │  └── src/            │
└─────────────────────┘            └──────────────────────┘

Multi-tenant: one install serves N projects. Each project gets project_hash = sha256(absolute_path).slice(0,12) and isolated state at ~/.stealthos/projects/<hash>/.

Stealth mode: your repo stays clean. Only .stealthos.yml + IDE stubs you picked land in your project.

See ADR-0012 for the full architecture and ADR-0013 for the alpha.8 pipeline.

What's in 1.1.0-beta.2 (Spec v1 LOCKED)

Pre-flight Environment Diagnostics (Installer Doctor): Automatically verifies Node.js, Git, and global CLI installation status before project setup.
Real-time Stack Detection: Auto-scans local dependencies (package.json, Cargo.toml, etc.) to detect framework stacks (Next.js, FastAPI, Django, NestJS, etc.) and pre-select defaults in the CLI.
Onboarding Playbook (STEALTHOS_TUTORIAL.md): Generates localized guides explaining /init, /sync, and /work workflow pipelines with reload cues for your IDEs.
Metadata Prefill: Shares local project context (niche/domain, stack preference, name) from .stealthos.yml to automatically pre-fill Tier 1 critical questions during /init.
Unified full-context.md: Sized by your LLM (Claude/Sonnet/Opus, GPT-4o/5, Gemini 1.5 Pro/Flash, Gemini 2.x) — read in a single tool call by /work.
Auto-sync after /work: Closes the loop: state stays fresh without manual /sync.
82 MCP tools including the cognitive pipeline (Phases 1-5) + base (aios_recommend_blueprint, aios_apply_blueprint, aios_compile_full_context, aios_doctor, aios_repair, aios_memory_gc, aios_audit_drift, aios_check_port, aios_dev_env_check).

Manual install (advanced)

npx stealthos-cli@beta install        # installs ~/.stealthos/ + server deps
npx stealthos-cli@beta status         # show install info
npx stealthos-cli@beta run init       # run a workflow without an MCP-capable IDE

Override paths:

STEALTHOS_HOME=/opt/stealthos npx stealthos-cli install

Development (working ON StealthOS)

git clone https://github.com/IgorKadu/stealthos
cd stealthos
npm install                                # workspace deps
npm run install:server                     # MCP server deps
npm run bundle-ai                          # sync .ai/ → packages/stealthos-cli/ai/
node packages/stealthos-cli/bin.cjs install --home ./_dev-home --skip-server-deps

Publish (maintainers):

npm run publish:all      # tests → bundle-ai → publishes both packages with --tag beta

Status

Beta (create-stealthos 1.1.0-beta.2, stealthos-cli 1.1.0-beta.2). Spec v1 LOCKED — see STEALTHOS-SPEC-v1.md. Capabilities:

1-command install with i18n banner (PT-BR/EN/ES/ZH/JA/FR)
Progressive /init with conditional branches and blueprint recommendation (9 templates: web, saas, crm, mobile, game, realtime, telemetry, ai-platform)
LLM-aware full-context.md compilation (8 LLM size tiers: Claude Opus/Sonnet/Haiku, GPT-4o/4/5, Gemini 1.5 Pro/Flash, Gemini 2.x) with mtime-invalidated cache
Auto-sync chain: /init → /sync → /work → auto-sync → /work …
Multi-tenant state (sha256(path).slice(0,12)) — one install serves N projects
82 MCP tools incl. network diagnostics, drift audit, doctor/repair, memory GC, and full 5-phase cognitive pipeline
Antigravity global MCP config auto-merge (~/.gemini/antigravity/mcp_config.json)
Pre-flight environment diagnostics (Installer Doctor) and real-time stack detection in the scaffolder CLI
Playbook generation (STEALTHOS_TUTORIAL.md) and metadata-based pre-filling of discovery questions
Project isolation via STEALTHOS_BASE_EXCLUDES + .stealthosignore
Native slash commands for Claude Code and Antigravity; tasks/snippets for VSCode
60 automated tests blocking publish without passing
Runtime validation (JSON-RPC -32602 on bad input + workflow JSON schema validation on load)
Recovery via stealthos doctor (6 checks) + stealthos repair --targets state|full_context|paused|all
Workflow engine with ||/&& branches, ${steps.X} refs, recursion depth limit, pause/resume

Docs índice

📖 STEALTHOS-SPEC-v1 — contrato canônico LOCKED em 1.0.0-beta.0
🚀 MIGRATION.md — alpha → beta (TLDR: nada quebra)
📋 CHANGELOG.md — histórico desde alpha.5
❓ FAQ.md — instalação / MCP / state / multi-LLM / troubleshooting
🧪 EVAL-SUITE.md — metodologia de testes
📝 ADRs — 17 decisões arquiteturais documentadas

Smoke test

Verifica install + scaffolding + doctor de ponta a ponta:

node scripts/smoke-test.mjs            # roda contra @beta (default)
node scripts/smoke-test.mjs --tag alpha # contra @alpha legado

Contributing

PRs welcome. Read .ai/CONTRACT.md and .ai/rules/dont.md before opening. ADRs in .ai/specs/ADR/.

Legacy alpha line

Para usuários que estão no canal alpha:

npx create-stealthos@alpha    # ainda funciona, mas não recebe novas features

A linha alpha está congelada. Recomendado migrar para @beta. Veja MIGRATION.md — TLDR: nada quebra, state é preservado.

License

MIT — use it, fork it, ship it.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Repository files navigation

StealthOS

Install in 1 command

The 3 commands

MCP connection — how it works

Generic MCP server entry

Per-IDE config

Troubleshooting MCP

Architecture

What's in 1.1.0-beta.2 (Spec v1 LOCKED)

Manual install (advanced)

Development (working ON StealthOS)

Status

Docs índice

Smoke test

Contributing

Legacy alpha line

License

About

Uh oh!

Releases

Packages

Uh oh!

Contributors

Uh oh!

Languages

Name		Name	Last commit message	Last commit date
Latest commit History 48 Commits
.agents/workflows		.agents/workflows
.ai		.ai
.claude		.claude
.continue		.continue
.cursor		.cursor
.gemini		.gemini
.github		.github
.trae/rules		.trae/rules
packages		packages
scripts		scripts
test		test
.clinerules		.clinerules
.cursorrules		.cursorrules
.gitattributes		.gitattributes
.gitignore		.gitignore
.stealthos.yml		.stealthos.yml
.stealthosignore		.stealthosignore
.windsurfrules		.windsurfrules
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
FAQ.md		FAQ.md
GEMINI.md		GEMINI.md
GPT.md		GPT.md
LICENSE		LICENSE
MIGRATION.md		MIGRATION.md
Objetvos.txt		Objetvos.txt
README.md		README.md
Relatorio de Teste.txt		Relatorio de Teste.txt
package-lock.json		package-lock.json
package.json		package.json

Folders and files

Latest commit

History

Repository files navigation

StealthOS

Install in 1 command

The 3 commands

MCP connection — how it works

Generic MCP server entry

Per-IDE config

Troubleshooting MCP

Architecture

What's in 1.1.0-beta.2 (Spec v1 LOCKED)

Manual install (advanced)

Development (working ON StealthOS)

Status

Docs índice

Smoke test

Contributing

Legacy alpha line

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages