Engineering OS

Give your AI coding tools a proper memory. Engineering OS sits on your machine, learns how your project works, and feeds that knowledge to Claude Code, Cursor, Codex, or any MCP-compatible AI code editor. They stop asking the same questions every session.

You know the drill: every new session, your AI re-explores files, re-debates decisions you already made, and has no idea your frontend talks to three backend services. engineering-os fixes that. One eos init and your AI knows everything. Permanently.

The Problem

Quick Start

1. Install

npm install -g engineering-os

2. Initialize in your project

cd your-project
eos init --claude --cursor

# Output:
# ✓ Repository indexed (847 files, 4201 chunks)
# ✓ Architecture discovered (12 services, 3 patterns)
# ✓ Graph built (156 calls, 4 contracts)
# ✓ CLAUDE.md generated
# ✓ .cursor/rules/ generated (5 files)
# ✨ Engineering OS initialized!

3. That's it — start coding

Open Claude Code or Cursor. Your AI now has full project knowledge. It will:

• Call eos_context before starting any task (gets routes, architecture, conventions)
• Use eos_search instead of grep/find (pre-indexed, instant results)
• Recall past decisions with eos_recall_decision (never re-debates)
• Learn from the session with eos_learn (gotchas persist forever)

4. Cross-repo (optional)

# Link sibling services for full architecture awareness
eos link backend-api ../backend-api
eos link mobile-app ../mobile-app

# Or declare in eos.workspace.yaml (team-shared, checked into git)
eos workspace add-repo backend-api ../backend-api --role bff

5. Keep fresh

# Auto-refresh after code changes (add to git post-commit hook)
eos refresh --incremental

# Or continuous watch mode
eos index --watch

Workspace Setup

Create eos.workspace.yaml in your project root. This file is checked into git — your entire team shares the same conventions and decisions.

# Team-shared project configuration — checked into git
name: acme-mobile
type: react-native-monorepo
org: acme-corp

# Linked repositories in your ecosystem
repos:
  - name: acme-gateway
    path: ../gateway          # API gateway configuration
    role: api-gateway
  - name: acme-api
    path: ../backend          # Main backend service (Spring Boot / Express)
    role: backend-service
  - name: acme-ml
    path: ../ml-pipeline      # Data science / ML inference
    role: ml-pipeline

# Coding conventions (enforced across all AI sessions)
conventions:
  - name: error-handling
    rule: "Use Result<T> pattern in services. Only controllers throw HTTP exceptions."
  - name: state-management
    rule: "Zustand stores only. No Redux. One store per domain."
  - name: api-calls
    rule: "All network calls go through the shared HTTP client. Never use raw fetch/axios."
  - name: file-naming
    rule: "kebab-case for files, PascalCase for components, camelCase for hooks"

# Settled decisions (AI will not re-debate these)
decisions:
  - title: "Redis for session store"
    decision: "Use Redis Cluster for all session management"
    rationale: "Sub-ms read latency, built-in expiry, horizontal scaling proven at load"
  - title: "API Gateway pattern"
    decision: "All client traffic routes through the gateway service"
    rationale: "Centralizes rate limiting, auth validation, and request transformation"

# Which AI tool context files to generate
ai:
  tools: [claude, cursor]
  mcp: true

Or build incrementally with the CLI:

# Create the workspace file with auto-detected project info
eos workspace init

# Add conventions one by one
eos workspace add-convention "testing" "Co-locate test files with source. Use vitest."
eos workspace add-convention "imports" "Use absolute imports via path aliases, not relative ../../"

# Record architectural decisions
eos workspace add-decision "Message Queue" "Kafka for event streaming" --rationale "Ordered delivery, replay capability, team expertise"

# Link sibling repositories
eos workspace add-repo gateway ../gateway --role api-gateway
eos workspace add-repo backend ../backend --role backend-service

Cross-Repo Linking

Declare linked repos in your workspace yaml. On eos init, they're automatically linked. When the AI calls eos_context, it returns data from all linked services.

Step 1: Declare linked services in workspace yaml

# In eos.workspace.yaml — declares the services your project talks to
repos:
  - name: order-service
    path: ../order-service     # relative path to sibling repo
    role: backend-service      # role helps EOS understand the relationship
  - name: payment-gateway
    path: ../payments
    role: payment-service
  - name: infra
    path: ../infrastructure
    role: devops

Step 2: Initialize (auto-links everything)

eos init --claude
# Output:
# ✓ Linked 3 repo(s) from workspace config
# ✓ Graph built (42 calls, 2 contracts)
# ✓ 5 connection(s) auto-linked

Step 3: Verify — AI now sees cross-repo context

When Claude calls eos_context, the response includes all linked services — their routes, file structure, GraphQL subgraphs, and infrastructure topology. Your AI knows the full architecture without exploring any files.

Skill Retention

EOS learns from every session. When the AI discovers something, it persists via eos_learn. Future sessions recall relevant skills automatically.

Recording a skill

When your AI discovers something during a session — a bug pattern, a non-obvious requirement, or a hidden dependency — it records it for all future sessions:

// AI discovered that file uploads must be ordered (not obvious from code)
eos_learn({
  type: "gotcha",
  name: "Chunked upload ordering",
  content: "File chunks must be uploaded sequentially — out-of-order chunks cause silent data corruption in the stitching service",
  context: "file upload feature, S3 multipart uploads",
  tags: ["upload", "s3", "multipart", "ordering"]
})

// AI learned a multi-step workflow pattern
eos_learn({
  type: "pattern",
  name: "Adding a new screen",
  content: "1. Create folder in src/screens/{Name}/ 2. Add index.tsx with screen component 3. Add route to src/navigation/types.ts 4. Register in RootNavigator.tsx 5. Create local Zustand store if needed",
  context: "creating new screens in the mobile app",
  tags: ["screen", "navigation", "mobile"]
})

// AI discovered a cross-service connection not visible in code
eos_learn({
  type: "connection",
  name: "Order completion triggers analytics",
  content: "When order-service publishes 'order.completed' to Kafka, the analytics-pipeline consumes it and updates BigQuery within ~30s",
  context: "order lifecycle, analytics pipeline",
  tags: ["kafka", "analytics", "order", "bigquery"]
})

Skill types

Skills auto-inject into tool responses when context matches. Confidence escalates with usage (medium → high after 5 applications).

AI Tool Integrations

Claude Code

Claude Code connects via MCP. Two files are generated:

// .mcp.json — tells Claude Code where the EOS server is
// (auto-created by eos init, no manual setup needed)
{
  "mcpServers": {
    "engineering-os": {
      "command": "eos",
      "args": ["serve"]
    }
  }
}

// CLAUDE.md — enforcement rules that instruct Claude:
// • ALWAYS call eos_context before starting work
// • NEVER use grep/find — use eos_search instead
// • ALWAYS call eos_learn when discovering something
// • NEVER make architecture decisions without eos_recall_decision

Cursor

Cursor loads per-topic rule files from .cursor/rules/. EOS generates 5 files, each serving a specific purpose:

eos init --cursor

# Generated files (all prefixed eos- to avoid conflicts with your rules):
# .cursor/rules/eos-system.md        → "Use EOS tools, don't explore"
# .cursor/rules/eos-conventions.md   → Project coding standards
# .cursor/rules/eos-architecture.md  → Service map and key directories
# .cursor/rules/eos-decisions.md     → Settled decisions (don't re-debate)
# .cursor/rules/eos-service-map.md   → Cross-repo dependency graph

Windsurf

Single rules file with EOS tool instructions:

eos init --windsurf
# Creates: .windsurfrules (same steering approach as CLAUDE.md)

Any MCP Client

CLI Reference

eos init

Initialize Engineering OS in the current repository.

eos serve

Start the MCP server. Works from any directory.

eos refresh

Update EOS knowledge after code changes.

eos workspace

eos workspace init
eos workspace show
eos workspace add-convention <name> <rule>
eos workspace add-decision <title> <decision> [--rationale <why>]
eos workspace add-repo <name> <path> [--role <role>]

eos link / unlink

eos index

API Reference — Knowledge Tools

// Example: AI calls this at session start
eos_context({ task: "add retry logic to file upload" })

// Returns ~1200 tokens of focused context:
// - Project overview (type, stack, packages)
// - Routes showing upload endpoints
// - Linked services (backend handling uploads)
// - Convention: "All network calls through shared HTTP client"
// - Skill: "⚠️ Chunks must be uploaded in order"
// - Relevant files: src/services/upload.ts, src/hooks/useUpload.ts

API Reference — Architecture Tools

API Reference — Learning Tools

API Reference — Workflow Tools

// Example
eos_build({
  requirement: "Add real-time order status notifications with WebSocket",
  mode: "plan-only"
})

// Returns structured plan:
// Product Spec: user stories, acceptance criteria
// Tech Spec: affects order-service (Kafka producer), notification-service (WebSocket),
//            mobile-app (UI component). Reuse: existing WebSocket infra from chat.
// Execution Plan:
//   Step 1 [BE-Engineer]: Add Kafka event to order-service
//   Step 2 [BE-Engineer]: WebSocket subscription in notification-service
//   Step 3 [FE-Engineer]: Status badge component in mobile app
//   Step 4 [DevOps-Engineer]: Scale WebSocket pods for load

API Reference — Security Tools

All Security & Compliance Tools

Complete Tool Reference (47 Tools)

Every MCP tool available when connected to the Engineering OS server.

Knowledge & Search

Architecture & Dependencies

Conventions & Decisions

Learning & Skills

Workflow & Planning

Multi-Repo & Team

Language & Framework Support

Code Indexing

EOS extracts functions, classes, interfaces, imports, and exports from these languages:

Route Scanning

Dependency Auditing (CVE Scanning)

Configuration Reference

eos.workspace.yaml

Storage Layout

Troubleshooting

MCP Connection Error: -32000

If you see Failed to reconnect to engineering-os: -32000 when running /mcp in Claude Code, this almost always means a Node.js version mismatch.

EOS uses better-sqlite3, a native C++ module compiled for a specific Node.js ABI version. If you installed EOS with one Node version (e.g., Node 24) but your shell defaults to another (e.g., Node 22), the native binary cannot load.

How to fix

# Check which Node version your shell defaults to
node --version

# Rebuild the native module for that version
npm rebuild better-sqlite3

# Or reinstall EOS globally with the current Node
npm install -g engineering-os

Why this happens

If you use nvm, your .zshrc or .bashrc may force a specific Node version (e.g., nvm use 22). Claude Code inherits this shell environment when spawning the MCP server. If you originally ran npm install with a different Node version, the compiled native module won't match.

Permanent fix

# Option A: Always install with the same Node your shell uses
nvm use 22       # or whatever your default is
npm install -g engineering-os

# Option B: Add a .nvmrc to avoid confusion
echo "22" > ~/.nvmrc

# Option C: Set nvm default to match your active version
nvm alias default 22

Rule of thumb: The Node version that runs npm install must match the Node version that runs eos serve.

MCP Server Not Found

If Claude Code can't find the eos command:

# Verify eos is installed and in PATH
which eos

# If not found, install globally
npm install -g engineering-os

# Verify it works
eos --version

No .eos/ Directory Found

The MCP server requires an initialized project. Run:

cd your-project
eos init --claude

If you're working from a directory that isn't a project root, use the --global flag or ensure the global registry has repos registered:

# Check registered repos
cat ~/.eos/repos.yaml

# Start server in global mode
eos serve --global

Database Locked Errors

If you see SQLite "database is locked" errors, it means two EOS processes are competing for the same database. This can happen if you have multiple Claude Code sessions open on the same project. Each session spawns its own eos serve process — this is safe (EOS uses WAL mode with busy timeout), but if you encounter issues:

# Find and kill stale eos processes
ps aux | grep "eos serve" | grep -v grep
kill 

# Then reconnect in Claude Code
/mcp

Slow Indexing

Initial indexing scans all source files. For very large repos (100K+ files), you can:

# Use incremental refresh after the initial index
eos refresh --incremental

# Or use git-based refresh for just recent changes
eos refresh --since=HEAD~5

Node.js Version Requirements