🧠 SIN-Code Bundle

The universal semantic backend for AI coding agents.

One CLI (sin) and one unified MCP server (sin-serve / sin serve) that orchestrate 7 Go tools and 5 external bridges — giving AI agents the signals they actually lack: structural knowledge, semantic diffs, correctness proofs, ephemeral test environments, debt guardrails, and persistent memory.

As of v0.9.3 (issue #28) the 6 Python subsystems (SCKG, IBD, PoC, EFM, ADW, Oracle) and the Next.js Web frontend are no longer vendored in this monorepo. They live in their own standalone OpenSIN-Code repos and are installed separately via requirements-ecosystem.txt. The Bundle has shrunk from ~50k LOC to the core glue: CLI + MCP server + VFS resolver + AST editor + sin-brain memory hooks.

⚡ Why SIN-Code? (The Anti-Dreck Promise)

Most coding agents operate blind — fragile string replacements, blind bash execution, no memory between sessions. SIN-Code replaces native agent tools with semantically aware, verifiable alternatives.

The Old Way (Dreck)	The SIN-Code Way
❌ Fragile `str_replace` (whitespace errors, stale files)	✅ `sin_edit`: Hashline-anchored, content-hash verified patching (line-shift resilient)
❌ Blind `read` (dumps 2000 lines of context)	✅ `sin_read`: Deep structural analysis OR semantic URIs (`sckg://module/auth/neighbors`) — size-safe with summarize mode
❌ Dangerous `bash` (secret leaks, infinite loops)	✅ `sin_bash`: Secret-redaction + strict timeouts + structured JSON (safety_check, retry_info)
❌ Stateless amnesia (forgets user prefs every session)	✅ `recall_tool`/`remember_tool`: Persistent 4-tier memory (SQLite+FTS5) via sin-brain
❌ Architectural drift (agents spaghetti-fy the code)	✅ `sin_check_architecture`: Pre-flight ADW rule enforcement — blocks hardcoded secrets, eval/exec, frontend-DB imports
❌ Sequential exploration (one slow task at a time)	✅ `sin_create_worktree`: Isolated git worktrees for parallel agent tasks without conflicts
❌ Static analysis only (no runtime insight)	✅ `sin_runtime_trace`: DAP debug session attachment (debugpy/dlv/node)

🚀 Quickstart (2-5 minutes)

git clone https://github.com/OpenSIN-Code/SIN-Code-Bundle.git
cd SIN-Code-Bundle
bash install.sh        # Bootstraps 7 Go tools + Python bundle + MCP config + 5 external bridges
sin status            # Show what's installed
sin bootstrap /path/to/your/repo   # Initialize graphs, baselines, ledgers
sin-serve             # Start the unified MCP server (or: sin serve)

Pair commands (symmetric to install.sh):

bash uninstall.sh     # Remove everything bash install.sh installed
bash update.sh        # Update in-place without full reinstall

Flags: --help, --dry-run, --verbose, --force, --skip-go, --skip-external, --with-externals

--with-externals upgrades the install from "check only" to actually auto-installing the external bridges: GitNexus (npm), MarkItDown (pipx/pip), RTK (brew), and Simone-MCP (npm in ~/dev/Simone-MCP). Without this flag, those tools are only verified/registered — the user must run sin xxx setup manually for each one.

Environment overrides:

SIN_CODE_BIN_DIR=~/custom-bin SIN_CODE_REPOS_DIR=~/my-repos bash install.sh
SIN_CODE_BIN_DIR=~/custom-bin bash install.sh --with-externals

Publishing to PyPI (one-time setup)

The release.yml workflow uses PyPI Trusted Publishing (no API tokens, no manual uploads). To enable it for the first time, the maintainer must register the publisher once.

Recommended (non-interactive, API token):

# 1. Generate a PyPI API token at https://pypi.org/manage/account/token/
#    (scope: "Entire account" works, or scope to a single project)
# 2. Run:
export PYPI_API_TOKEN="pypi-..."
python -m sin_code_bundle.tools.pypi_setup --api-token "$PYPI_API_TOKEN"
# 3. Check your email, click the magic link PyPI sent

This is the 1-click path: no TTY, no prompts, no 2FA dance. It works in CI scripts, agents, and headless servers. See pypi_setup.doc.md for the full failure-mode table and security notes.

Legacy fallback (interactive username + password):

bash tools/setup_pypi_publisher.sh
# Follow the prompts, check email, click the magic link

Kept for maintainers who do not have a PyPI API token. Does not work in CI / non-TTY environments.

After this one-time setup, every git tag v0.X.Y && git push origin v0.X.Y triggers:

Build sdist + wheel
Verify install in a clean venv
Publish to PyPI via Trusted Publisher (tokenless OIDC)
Attach assets to GitHub Release

Manual fallback: https://pypi.org/manage/account/publishing/ — Add pending publisher:

Project: sin-code-bundle (PEP 503 normalised)
Owner: OpenSIN-Code
Repo: SIN-Code-Bundle
Workflow filename: release.yml
Environment name: pypi

🛠️ Agent Usage Example

Instead of guessing file structures, agents query the Semantic Codebase Knowledge Graph (SCKG) directly via stable URI schemes:

// Agent tool call
{
  "name": "sin_read",
  "arguments": {
    "path": "sckg://module/auth-service/dependencies",
    "summarize": true
  }
}

The VFS resolver translates this into a structured JSON response of exact module dependencies — saving hundreds of tokens and preventing hallucination.

To disable native opencode tools and force SIN-Code usage, add to ~/.config/opencode/opencode.json:

{
  "tools": {
    "read": false, "write": false, "edit": false, "bash": false,
    "search": false, "find": false, "grep": false, "glob": false,
    "list": false, "webfetch": false, "task": false
  },
  "mcp": {
    "sin-code-bundle": {
      "type": "local",
      "command": ["sin", "serve"],
      "enabled": true
    }
  }
}

📦 Unified MCP Tool Inventory (37 Tools)

When sin-serve is running, agents get 37 tools. Native opencode tools should be disabled to enforce SIN-Code usage.

Core File Operations (5) — Replace native read/write/edit/bash/search

Tool	Replaces	What it does	Why better than native
`sin_read`	`read`	URI-aware file read with size-safety + summarize mode	Native dumps 10MB+ into context; sin_read truncates + supports `sckg://`, `poc://`, `ibd://`, `adw://`, `efsm://`, `oracle://`, `conflict://` URIs
`sin_write`	`write`	Atomic write + syntax pre-validation (.py/.ts/.js/.go) + auto-backup	Native creates half-written files on crash; sin_write is atomic + compiles before writing
`sin_edit`	`edit`	Hashline-anchored semantic patches (content-hash, not line numbers)	Native edit breaks on reformat/race; sin_edit survives line shifts
`sin_bash`	`bash`	Safe shell exec via Go `execute` binary	Native leaks secrets; sin_bash redacts tokens/keys + enforces timeout
`sin_search`	`search`/`find`/`grep`/`glob`	Scout (Go) + Python-regex fallback	Native has 4 separate tools; sin_search unifies all 4 with semantic mode

Virtual Filesystem — URI Schemes (2)

Tool	What it does
`sin_vfs_resolve`	Resolve `sckg://`, `poc://`, `ibd://`, `adw://`, `efsm://`, `oracle://`, `conflict://` URIs to structured content
`sin_vfs_schemes`	List all available URI schemes

Code Structure — AST + Hashline (2)

Tool	What it does
`sin_ast_edit`	Tree-sitter AST-based edit with POC verification (falls back to hashline)
`sin_hashline_validate`	Validate a previously-created hashline patch can still be applied

Architectural Enforcement (1)

Tool	What it does
`sin_check_architecture`	Pre-flight ADW rule check — blocks hardcoded secrets, eval/exec, frontend-DB imports

Consolidation Tools (3) — v0.7.0 — Replace 3-4 separate calls with 1

Tool	Replaces	What it does
`sin_preflight`	`sin_check_architecture` + `sin_bash("sin codocs check")` + `sin_bash("git status")` + `sin_bash("pytest --collect-only")`	Pre-flight safety gate: policy + docs + git + tests in 1 call. Returns `{allowed, policy_ok, docs_ok, git_clean, tests_status, estimated_risk}`
`sin_symbol_resolve`	`gitnexus_query` + `gitnexus_context` + `gitnexus_impact` + `gitnexus_detect_changes`	Unified code archaeology for a symbol. Fans out to 4 gitnexus primitives + optional sin-context-bridge. Returns unified graph view with `sources_queried` list
`sin_checkpoint`	`rollback_snapshot` + `sin_bash("sin codocs check")` + `sin_bash("git status")` + `sin_search("X", type="usage")` + `sin_bash("pytest --collect-only")`	Pre-refactor checkpoint: recoverable snapshot + state report in 1 call. Idempotent on `name`. Returns `{snapshot_id, docs_broken, git_clean, usages_found, tests_status, tests_collected}`

Runtime Debugging — DAP (2)

Tool	What it does
`sin_runtime_trace`	Start a DAP debug session for a function (debugpy for Python, dlv for Go, node --inspect for Node)
`sin_stop_trace`	Stop an active DAP session

Parallel Task Execution (2)

Tool	What it does
`sin_create_worktree`	Create an isolated git worktree for parallel agent tasks
`sin_cleanup_worktree`	Clean up worktree (optionally merge back to main)

Subsystem Tools (10) — Require subsystem packages via `pip install -e ".[all]"`

Tool	Subsystem	What it does
`impact`	sin_code_sckg	Blast-radius impact analysis for a symbol
`semantic_diff`	sin_code_ibd	Semantic intent diff between two files
`semantic_review`	sin_code_ibd	Intent + risk score in one call
`architectural_debt`	sin_code_adw	Current architectural debt score (god modules, circular imports, hot paths without tests)
`verify_tests`	sin_code_oracle	Verify agent-generated code (security/perf/correctness — OWASP Top 10, CWE Top 25)
`prove`	sin_code_poc	Generate and verify proofs of correctness (Hoare-style pre/post-conditions)
`mock_env`	sin_code_efsm	Manage ephemeral full-stack mock environment (Postgres + Redis + API server in 10s)
`orchestrate`	sin_code_orchestration	Submit a task to the multi-agent orchestrator (dependency-graph aware)
`task_status`	sin_code_orchestration	Get status of an orchestrated task
`review`	sin_code_review_interface	SOTA review on a single file (diff + debt + tests + style)

Memory Tools (5) — Require `sin-brain` via `pip install -e ".[memory]"`

Tool	What it does
`recall_tool`	Search memory tiers (recall/archival/graph) — 4-tier SQLite+FTS5 storage
`remember_tool`	Persist a memory (decision/convention/fix/pitfall/preference)
`forget_tool`	Delete a memory entry by id
`pin_tool`	Pin a memory entry (never evicted)
`link_evidence_tool`	Attach a subsystem verdict to a memory

External Bridges (5)

Tool	Source	What it does
`gitnexus_context`	GitNexus (PolyForm-Noncommercial)	Structural graph context for a symbol
`gitnexus_impact`	GitNexus	Blast-radius impact via graph (auto-indexes)
`gitnexus_ai_context`	GitNexus	Task-scoped, graph-aware context bundle
`markitdown_convert`	MarkItDown (MIT)	Convert PDF/DOCX/PPTX/XLSX/image → Markdown
`codocs_check`	codocs (built-in)	Find broken co-located `.doc.md` references

Total: 34 tools = 5 core + 2 VFS + 2 AST + 1 arch + 2 runtime + 2 worktree + 10 subsystem + 5 memory + 5 external

🔌 Bridged External Tools (Never Vendored)

To keep the bundle MIT-licensed and lightweight, these upstream tools are bridged (installed and updated independently, never vendored):

Tool	Purpose	License	Setup
GitNexus	Upstream code knowledge graph	PolyForm-Noncommercial	`sin gitnexus setup`
Simone-MCP	Advanced code intelligence + LSP	Varies	Auto-detected during `sin bootstrap`
MarkItDown	Document → Markdown converter	MIT	`sin markitdown setup`
RTK	Token-saving shell proxy (60-90% reduction)	Apache-2.0	`sin rtk setup`

🧩 Companion Skills (Separate MCP Servers)

The Bundle exposes 37 tools via sin serve. Several companion skills ship as separate MCP servers — they are not part of the bundle core, but register cleanly alongside it in any opencode / Claude Code / Cursor config.

Companion	Tools	Install	Run
sin-context-bridge	2 tools — unified context across SCKG + sin-brain + GitNexus + local SQLite	`pip install sin-code-bundle[all]`	`sin-context-bridge serve`
sin-honcho-rollback	4 MCP tools + CLI — snapshot, rollback, audit log for sin-brain memory	`pip install sin-honcho-rollback`	`sin-honcho-rollback serve`
symfony-lens	8 tools — Symfony-specific static analysis (services, routes, entities, Twig, migrations, PHPStan)	`pip install sin-code-symfony-lens`	`python -m symfony_lens.server`

Wire them into opencode

{
  "mcp": {
    "sin-code-bundle":     { "type": "local", "command": ["sin", "serve"] },
    "sin-context-bridge":  { "type": "local", "command": ["sin-context-bridge", "serve"] },
    "sin-honcho-rollback": { "type": "local", "command": ["sin-honcho-rollback", "serve"] },
    "symfony-lens":        { "type": "local", "command": ["symfony-lens"] }
  }
}

All three companions follow the Bundle's graceful-degradation contract: if the server isn't running, the consumer falls back to local-only behaviour without crashing.

🛡️ Graceful Degradation

Every subsystem is an optional dependency. If a subsystem is missing, the MCP server detects it and gracefully falls back. The bundle never crashes on a missing optional dep.

pip install -e ".[all]"     # All 8 Python subsystems + sin-brain + LSP
pip install -e ".[memory]"  # Just sin-brain (memory tools)
pip install -e ".[lsp]"     # tree-sitter + 4 parsers (Python <3.14 only)
pip install -e "."          # Minimal — uses graceful fallbacks

Check what's installed:

sin status

🏗️ Architecture

┌─────────────────────────────────────────────────────────────┐
│ sin-serve MCP server (stdio)                                │
│   19 tools exposed (5 core + 2 VFS + 2 AST + 1 arch +       │
│   2 runtime + 2 worktree + 5 memory) + 10 OPTIONAL          │
│   ecosystem tools (SCKG, IBD, PoC, EFM, ADW, Oracle + ... ) │
│   loaded only when the matching pip pkg is installed.       │
└─────────────────────────────────────────────────────────────┘
                          │
       ┌──────────────────┼──────────────────┐
       │                  │                  │
       ▼                  ▼                  ▼
┌────────────┐   ┌──────────────┐   ┌──────────────────┐
│ 7 Go tools │   │ 6+2 ECOSYSTEM│   │ 5 External       │
│ (grasp,    │   │ packages     │   │ bridges          │
│  scout,    │   │ (sckg, ibd,  │   │ (GitNexus,       │
│  discover, │   │  poc, efsm,  │   │  Simone-MCP,     │
│  execute,  │   │  adw, oracle,│   │  MarkItDown,     │
│  map,      │   │  orchestration│  │  RTK, codocs)    │
│  harvest,  │   │  review-     │   │                  │
│  orchestrate)│ │  interface)  │   │                  │
└────────────┘   └──────────────┘   └──────────────────┘
                          ▲
                          │ pip install -r
                          │   requirements-ecosystem.txt
                          │
                  ┌──────────────┐
                  │ sin-brain    │
                  │ (SQLite+FTS5 │
                  │ memory)      │
                  └──────────────┘

Ecosystem packages (SCKG, IBD, PoC, EFM, ADW, Oracle, Orchestration, Review-Interface) are NOT vendored in this monorepo anymore (issue #28). Install them from their standalone repos via requirements-ecosystem.txt. Each is a standard pip-installable package with its own README + LICENSE.

Ecosystem pkg Standalone repo Description

sin-code-sckg SIN-Code-SCKG-Tool Semantic Codebase Knowledge Graphs

sin-code-ibd SIN-Code-IBD-Tool Intent-Based Diffing

sin-code-poc SIN-Code-PoC-Tool Proof-of-Correctness

sin-code-efsm SIN-Code-EFM-Tool Ephemeral Full-Stack Mocking

sin-code-adw SIN-Code-ADW-Tool Architectural Debt Watchdog

sin-code-oracle SIN-Code-Oracle-Tool Verification Oracle

The Next.js web frontend lives in SIN-Code-Bundle-Web.

Ecosystem pkg	Standalone repo	Description
`sin-code-sckg`	SIN-Code-SCKG-Tool	Semantic Codebase Knowledge Graphs
`sin-code-ibd`	SIN-Code-IBD-Tool	Intent-Based Diffing
`sin-code-poc`	SIN-Code-PoC-Tool	Proof-of-Correctness
`sin-code-efsm`	SIN-Code-EFM-Tool	Ephemeral Full-Stack Mocking
`sin-code-adw`	SIN-Code-ADW-Tool	Architectural Debt Watchdog
`sin-code-oracle`	SIN-Code-Oracle-Tool	Verification Oracle

🧰 CLI Commands

Command	Description
`sin status`	Show which subsystems are installed/available
`sin bootstrap [repo]`	Initialize available subsystems (graph, baselines, ledger)
`sin review <a> <b>`	Semantic review of a change (IBD)
`sin verify <module> <fn>`	Proof-of-correctness for a function (POC)
`sin debt [root]`	Architectural debt overview (ADW)
`sin preflight [root]`	Ensure GitNexus graph context is fresh before agents code
`sin gitnexus setup`	Wire GitNexus MCP into OpenCode / Codex / Hermes
`sin gitnexus index\|status\|doctor\|context\|impact\|ai-context`	GitNexus graph operations
`sin markitdown setup\|doctor\|convert`	Wire/convert via MarkItDown (doc → Markdown)
`sin rtk setup\|doctor\|gain`	Wire RTK token-saving proxy into agents
`sin codocs check [root]`	Validate co-located `.doc.md` references (built-in)
`sin codocs list [root]`	List all CoDocs references and whether they resolve
`sin codocs install-skill`	Install the CoDocs agent skill (Hermes / OpenCode)
`sin sin-code run <tool> [args]`	Run a SIN-Code Go tool (discover, execute, map, grasp, scout, harvest, orchestrate)
`sin sin-code agents-md`	Generate AGENTS.md with SIN-Code Tool Suite rules
`sin serve`	Unified MCP server across available subsystems

🦫 SIN-Code Go Tools (v2)

The next-generation SIN-Code tools are Go binaries that replace OpenCode's built-in tools (auto-installed by install.sh):

Tool	Purpose	Version
`discover`	File discovery with pattern matching, relevance scoring, dependency mapping	v0.2.5
`execute`	Safe command execution with secret redaction, timeout, error analysis	v0.2.4
`map`	Architecture analysis with module mapping, entry points, hot paths	v0.2.5
`grasp`	Single-file deep analysis with structure, dependencies, context	v0.2.4
`scout`	Code search with regex, semantic, symbol, usage modes	v0.1.5
`harvest`	URL/API fetching with caching, structure extraction, auth management	v0.1.4
`orchestrate`	Task management with dependencies, parallel execution, rollback	v0.1.6

Install manually:

go install github.com/OpenSIN-Code/SIN-Code-Discover-Tool/cmd/discover@latest
go install github.com/OpenSIN-Code/SIN-Code-Execute-Tool/cmd/execute@latest
go install github.com/OpenSIN-Code/SIN-Code-Map-Tool/cmd/map@latest
go install github.com/OpenSIN-Code/SIN-Code-Grasp-Tool/cmd/grasp@latest
go install github.com/OpenSIN-Code/SIN-Code-Scout-Tool/cmd/scout@latest
go install github.com/OpenSIN-Code/SIN-Code-Harvest-Tool/cmd/harvest@latest
go install github.com/OpenSIN-Code/SIN-Code-Orchestrate-Tool/cmd/orchestrate@latest

📚 Documentation

INSTALL.md — Detailed installation and troubleshooting
CHANGELOG.md — Version history
docs/USAGE.md — Deep dive into CLI + MCP tool usage
docs/CONFIGURATION.md — Configuration reference
docs/EXTERNAL_TOOLS.md — Full compatibility matrix
docs/GITNEXUS.md — How to wire the mandatory graph context
docs/CODOCS.md — Co-located .doc.md standard
docs/adr/ — Architecture Decision Records
CONTRIBUTING.md — How to contribute

🤝 License

MIT — see LICENSE.

Bridged tools retain their original licenses:

GitNexus: PolyForm-Noncommercial
MarkItDown: MIT
RTK: Apache-2.0

Part of the SIN-Code agent-engineering stack.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

🧠 SIN-Code Bundle

⚡ Why SIN-Code? (The Anti-Dreck Promise)

🚀 Quickstart (2-5 minutes)

Publishing to PyPI (one-time setup)

🛠️ Agent Usage Example

📦 Unified MCP Tool Inventory (37 Tools)

Core File Operations (5) — Replace native read/write/edit/bash/search

Virtual Filesystem — URI Schemes (2)

Code Structure — AST + Hashline (2)

Architectural Enforcement (1)

Consolidation Tools (3) — v0.7.0 — Replace 3-4 separate calls with 1

Runtime Debugging — DAP (2)

Parallel Task Execution (2)

Subsystem Tools (10) — Require subsystem packages via `pip install -e ".[all]"`

Memory Tools (5) — Require `sin-brain` via `pip install -e ".[memory]"`

External Bridges (5)

🔌 Bridged External Tools (Never Vendored)

🧩 Companion Skills (Separate MCP Servers)

Wire them into opencode

🛡️ Graceful Degradation

🏗️ Architecture

🧰 CLI Commands

🦫 SIN-Code Go Tools (v2)

📚 Documentation

🤝 License

FilesExpand file tree

README.md

Latest commit

History

README.md

File metadata and controls

🧠 SIN-Code Bundle

⚡ Why SIN-Code? (The Anti-Dreck Promise)

🚀 Quickstart (2-5 minutes)

Publishing to PyPI (one-time setup)

🛠️ Agent Usage Example

📦 Unified MCP Tool Inventory (37 Tools)

Core File Operations (5) — Replace native read/write/edit/bash/search

Virtual Filesystem — URI Schemes (2)

Code Structure — AST + Hashline (2)

Architectural Enforcement (1)

Consolidation Tools (3) — v0.7.0 — Replace 3-4 separate calls with 1

Runtime Debugging — DAP (2)

Parallel Task Execution (2)

Subsystem Tools (10) — Require subsystem packages via pip install -e ".[all]"

Memory Tools (5) — Require sin-brain via pip install -e ".[memory]"

External Bridges (5)

🔌 Bridged External Tools (Never Vendored)

🧩 Companion Skills (Separate MCP Servers)

Wire them into opencode

🛡️ Graceful Degradation

🏗️ Architecture

🧰 CLI Commands

🦫 SIN-Code Go Tools (v2)

📚 Documentation

🤝 License

Subsystem Tools (10) — Require subsystem packages via `pip install -e ".[all]"`

Memory Tools (5) — Require `sin-brain` via `pip install -e ".[memory]"`