Code Agent

Code Agent pushes vibe-hnindex from a search server to a coding agent runtime. Instead of AI assistants calling search 5-15 times, reading files one by one, and accumulating context noise, Code Agent delivers everything needed in 2 calls.

Why Code Agent?

In a typical AI coding session, the assistant wastes 60%+ of its first turn just retrieving context — multiple searches, reading files, filtering noise. This is called context rot: irrelevant search results accumulating in the context window, degrading reasoning quality.

code_session — Context Gathering

One call that replaces 5-15 separate search + read operations. Returns a structured context package with everything the AI needs to reason about a code change.

Usage

code_session(
  project_name: "my-app",
  task: "add rate limiting middleware to Express API",
  target_files: ["src/api/auth.ts"]  // optional
)

What It Returns

What Happens Internally

code_session("add rate limiting", "my-app")
  → detect task type: add-feature
  → smart_context() — analyze impact, find patterns
  → search() keyword × 3 — exact symbol matching
  → search() semantic × 1 — natural language understanding
  → read_file() × N — full content of relevant files
  → dependency_check() — package.json analysis
  → find_test_files() — locate related tests
  → impact_analysis() — who depends on these files?
  → package → return structured JSON

code_apply — Safe Code Changes

Apply code changes proposed by the AI. Respects safety scopes, runs tests, lint, and typecheck automatically.

Usage

code_apply(
  project_name: "my-app",
  session_id: "cs_...",         // from code_session (optional)
  edits: [
    {
      action: "create",
      file_path: "src/middleware/rate-limit.ts",
      content: "import rateLimit from 'express-rate-limit';\n..."
    },
    {
      action: "modify",
      file_path: "src/api/auth.ts",
      diff: "@@ -1,5 +1,6 @@\n import express...\n+import { apiLimiter }..."
    }
  ],
  verify: true                    // run tests after applying (default: true)
)

Edit Actions

Safety Scopes

Configure via CODE_AGENT_SCOPE env var (default: moderate):

Auto-Verification

When verify: true (default), code_apply automatically runs:

• Tests — Detects vitest, jest, pytest, or npm test
• Lint — Runs npm run lint if available
• TypeCheck — Runs tsc --noEmit for TypeScript projects

If tests fail, the result includes the failure output so the AI can iterate and fix.

Setup

Code Agent is opt-in. Add these to your MCP config to enable:

{
  "mcpServers": {
    "vibe-hnindex": {
      "command": "npx",
      "args": ["-y", "vibe-hnindex"],
      "env": {
        "OLLAMA_URL": "http://localhost:11434",
        "OLLAMA_MODEL": "bge-m3:567m",
        "QDRANT_URL": "http://localhost:6333",
        "CODE_AGENT_ENABLED": "true",
        "CODE_AGENT_SCOPE": "moderate"
      }
    }
  }
}

Or with the CLI (v0.11.1+):

hnindex init --mcp claude

The CLI automatically includes CODE_AGENT_ENABLED=true and CODE_AGENT_SCOPE=moderate in the generated config.

Best Practices

1. Always start with code_session — gather context before making changes. Avoids blind edits.
2. Review the context package — check similar patterns, test files, and impact analysis before deciding what to edit.
3. Use verify=true (default) — let the server run tests and report failures immediately.
4. Stay in moderate scope — it provides the best balance of safety and capability.
5. One task per session— don't combine multiple unrelated changes in one code_apply call.
6. Commit before applying — especially in full scope, having a git checkpoint makes rollback trivial.

Code Agent vs Smart Context

Smart Context is great for exploration. Code Agent is for execution. They complement each other — use smart_context to understand, code_agent to implement.