<div align="center">

syzgy

Stop babysitting your AI. Let it ship production-ready code.

Quality enforcement layer for agentic AI coding tools — built specifically for lightweight models that drift, hallucinate, and ship broken code confidently.

npx syzgy

</div>

The real problem

You're using a fast, affordable model — not the heavyweight flagship.

It's great for simple tasks. But the moment complexity spikes, it starts:

• Ignoring constraints halfway through the prompt
• Generating code that looks correct but silently fails
• Looping on the same mistake when asked to fix it
• Dumping your entire codebase into context and losing track of what matters

Thinking mode helps — but it's still the model talking to itself. It can't enforce structure it doesn't naturally follow.

syzgy enforces that structure from the outside.

It wraps your agent in a pipeline: decompose → compile → verify → reflect. The model just executes one scoped task at a time, with constraints it can't ignore and a verifier that catches errors before they reach you.

What it actually does

Without syzgy:
  You: "build JWT auth endpoint"
  Agent: *generates 200 lines, confident, wrong in 3 places*
  You: *debug for 20 minutes*

With syzgy:
  You: "build JWT auth endpoint"
  Agent: analyze → decompose into 6 sub-tasks
         → compile optimized prompt for sub-task 1
         → generate → verify (syntax + types + lint)
         → FAIL: TypeError on line 14
         → reflect with exact error context
         → retry → verify → PASS
         → sub-task 2...
  You: *working code, no debugging*

The agent follows this workflow automatically by reading the skill file syzgy installs. You don't change how you work.

Supported tools

Quality & Performance

The quality and reliability of syzgy are measured through rigorous automated benchmarks and manual inspections.

Benchmark Summary

<!-- BENCHMARK-TABLE-START -->

<!-- BENCHMARK-TABLE-END -->

• Full Automated Benchmark Report — Detailed latency, reflection cycles, and task completion metrics.
• Manual Evaluation Report — MCP Inspector tool schema and live verification logs.

Requirements

Python packages are installed automatically on first run.

Install

npx syzgy

First run does everything automatically:

1. Scans for installed AI tools
2. Checks Python 3.10+ availability
3. Installs Python dependencies
4. Starts background SSE daemon on port 3141
5. Registers the MCP server with every detected tool
6. Installs workflow instruction files per tool
7. Seeds the few-shot cache with baseline examples

After install: restart your AI tool, then verify with health_check().

Commands

# First run / full setup
npx syzgy                            # auto-detect + install + start + register all

# Enable / disable
npx syzgy enable                     # start daemon + register all detected tools
npx syzgy enable --claude-code       # register one tool only
npx syzgy enable --gemini-cli --cursor  # register multiple
npx syzgy disable                    # stop daemon + unregister all
npx syzgy disable --cursor           # remove one tool, keep daemon running

# Daemon control
npx syzgy start                      # start daemon only
npx syzgy stop                       # stop daemon only
npx syzgy restart                    # restart daemon

# Info
npx syzgy status                     # show daemon + registered tools
npx syzgy update                     # reinstall deps + re-seed cache + restart

Tool flags

MCP tools your agent gets

Once registered, your agent has access to these tools and follows the workflow automatically:

Verification layers

Layer 3 deliberately uses the agent's existing model. No extra cost.

Honest limitations

Context pruner uses keyword matching, not embeddings. Chunks must share literal words with the task to be kept. For semantic matching, install: pip install chromadb

Reflection loop is capped at 2 by default. For genuinely hard tasks, the agent will escalate to you after 2 failed attempts. This is intentional — prevents infinite loops. Adjustable in config.yaml.

Overhead on simple tasks. Every task triggers analyze_task() first. If classified as "simple", the pipeline is bypassed. But there's still one extra tool call. For quick one-liners, the overhead exists.

Best used for: multi-step features, anything with auth/security/db, refactors with clear requirements. Less useful for: exploratory work, architecture decisions, tasks where requirements are undefined.

How the workflow runs

User prompt
     │
     ▼
analyze_task()          ← is this simple, medium, or complex?
     │
     ├── simple ──────► compile_prompt() → generate → verify_code() → done
     │
     └── complex ─────► decompose_task()
                              │
                         for each sub-task:
                              │
                              ▼
                         compile_prompt()     ← optimized, scoped prompt
                              │
                         [if codebase context needed]
                         prune_context()      ← only relevant chunks
                              │
                              ▼
                         agent generates code
                              │
                              ▼
                         verify_code()
                              │
                         PASS ─────────────► add_example() → next sub-task
                              │
                         FAIL ─────────────► inject_reflection()
                                                    │
                                              retry (max 2x)
                                                    │
                                              still failing → escalate to user

Architecture

npx syzgy
     │
     ├── src/detect.js      scan for installed AI tools
     ├── src/deps.js        check Python + auto-install pip deps
     ├── src/daemon.js      spawn SSE server as background process
     ├── src/register.js    write MCP config to each tool's settings
     └── src/skills.js      install workflow instruction files per tool
                │
                ▼
     python/server.py       FastMCP server (stdio + SSE dual transport)
     python/core/
       ├── classifier.py    heuristic complexity classifier
       ├── compiler.py      prompt optimizer
       ├── decomposer.py    task → ordered sub-tasks
       ├── context_manager.py  keyword-based context pruner
       ├── verifier.py      3-layer verifier
       ├── reflection.py    reflection injector + circuit breaker
       └── cache.py         few-shot cache (ChromaDB or keyword fallback)

The SSE daemon runs on localhost:3141 and persists in the background. State is stored in ~/.syzgy/state.json. PID is tracked in ~/.syzgy/daemon.pid.

Configuration

~/.syzgy/python/config/config.yaml:

complexity:
  complex_threshold: 2      # signals needed to classify as "complex"

verifier:
  max_reflection_loops: 2   # max retries before escalating to user

context:
  default_max_tokens: 3000
  relevance_threshold: 0.20 # keyword overlap cutoff (0–1, lower = more inclusive)

cache:
  top_k: 2                  # few-shot examples injected per task

Troubleshooting

Daemon not starting

npx syzgy status
cat ~/.syzgy/logs/daemon.log

Tool not detected

npx syzgy enable --claude-code   # force-register specific tool

Python not found

python3 --version   # needs 3.10+
# install: https://python.org/downloads

Full reset

npx syzgy disable
rm -rf ~/.syzgy
npx syzgy

Development

git clone https://github.com/RizkiRdm/syzygy-mcp-layer.git
cd syzygy-mcp-layer

pip install -r python/requirements.txt
python -m unittest discover -s tests -p "test_*.py" -v

node --check bin/cli.js src/*.js

python python/server.py --transport sse --port 3141 --debug

Project structure

syzgy/
├── bin/cli.js              npx entry point
├── src/
│   ├── utils.js
│   ├── detect.js
│   ├── deps.js
│   ├── daemon.js
│   ├── register.js
│   └── skills.js
├── python/
│   ├── server.py
│   ├── seed_cache.py
│   ├── requirements.txt
│   ├── config/config.yaml
│   └── core/
│       ├── classifier.py
│       ├── compiler.py
│       ├── decomposer.py
│       ├── context_manager.py
│       ├── verifier.py
│       ├── reflection.py
│       └── cache.py
├── skills/
│   ├── CLAUDE.md
│   ├── GEMINI.md
│   ├── skill.md
│   ├── .cursorrules
│   └── copilot-instructions.md
└── tests/
    ├── test_core.py
    ├── test_cache.py
    └── test_integration.py

Uninstall

npx syzgy disable
rm -rf ~/.syzgy

License

MIT — RizkiRdm