SIN-Code-Bundle

README

🧠 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:

1. Build sdist + wheel
2. Verify install in a clean venv
3. Publish to PyPI via Trusted Publisher (tokenless OIDC)
4. 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.

---

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