Skip to content

rizvee/Code-Steward

BranchesTags

Repository files navigation

Code-Steward

Hero banner

Build Status License npm version Stars

The AI-native technical debt janitor. Detect, explain, and fix AI-generated code rot — 100% locally.

Table of Contents

Why Code-Steward

Code-Steward is the public launch platform for local-first AI remediation. It helps teams identify AI-generated technical debt, quantify risk, and fix code safely in a review-friendly workflow.

  • Detect AI-generated code rot with purpose-built smell analysis.
  • Quantify remediation risk with transparent Technical Debt Ratio (TDR).
  • Repair code in an isolated shadow workspace before changing history.
  • Create GitHub pull requests with human-readable thought traces.
  • Keep everything on your machine with zero cloud egress.

Features

  • 🚦 TDR Auditor — compute a clear Technical Debt Ratio from AI-smells and remediation risk.
  • 🧠 Refactor Engine — generate fix plans and execute them in a shadow workspace.
  • 🕵️ AI-Smell Detection — detect 12 AI-native smells, including context poisoning, silent failure paths, and brittle type boundaries.
  • 🛡️ Local-First — analysis and inference stay local; no external LLM APIs required.
  • 🧾 PR Generator — push a branch and open a GitHub pull request with verification metadata.
  • 🤖 Steward Bot — CI/CD automation that validates PR safety and reports TDR deltas.
  • 🌐 Multi-language support — TypeScript, Rust, JSON, YAML, and other common formats.
  • 🔗 MCP tool bridge — expose local tools securely to assistant workflows.
  • 📊 Verification metrics — track coverage, new smells, and test pass rates.
  • 🔄 Repeatable workflow — audit → plan → execute → verify → PR.

Installation

Prerequisites

  • Rust toolchain installed
  • Node.js 20+
  • Git
  • Ollama installed locally
  • DeepSeek-R1 model available in Ollama
  • GitHub CLI or a GitHub token for PR creation

Local build

npm install
npm run build:core
npm run build

Run locally

cd cli && npm run start
# or start the MCP server service
cd mcp-server && npm run dev

Docker

docker build -t codesteward/mcp-server .
docker run --rm -p 4200:4200 codesteward/mcp-server

Verify installation

npm run test

Publish the CLI package

The CLI package is now configured for npm publication.

cd cli
npm install
npm run build
npm login
npm publish --access public

If you want to check the package contents before publishing:

cd cli
npm pack --dry-run

Make sure the package name in cli/package.json is unique on npm before publishing.

Deployment

Production build

npm install
npm run build

Container deployment

docker build -t codesteward/mcp-server .
docker run --rm -p 4200:4200 codesteward/mcp-server

Deployment guidelines

  • Build the Rust core first using npm run build:core or let the Dockerfile build it automatically.
  • Use npm run test before deployment to validate the CLI and MCP server.
  • Set CODESTEWARD_AUDIT_LOG_DIR to a persistent storage path in production.
  • Keep local-only agent metadata out of version control: .agents/ and skills-lock.json are ignored.
  • Prefer container orchestration (Kubernetes, Docker Compose, or systemd) for production runs.

Quick Start

Start in the first five minutes with a new or existing repository.

git clone https://github.com/codesteward/sample-project.git
cd sample-project
codesteward audit --target .
codesteward fix --target .
codesteward pr

Demo placeholder

First 5 Minutes Demo

$ codesteward audit --target .
Analyzing repository...
TDR: 0.41
Smells found: 8
Status: review recommended

Then run the fix pipeline:

$ codesteward fix --target .
Planning remediation...
Applying verified fix in shadow workspace...
Verification passed.
Saved fix metadata to ~/.codesteward/last-fix.json

Open a PR when ready:

$ codesteward pr
Creating branch code-steward/fix-2026-05-06...
Applying patch...
Pushing branch...
Pull request created: https://github.com/codesteward/codesteward/pull/123

Usage Guide

codesteward audit

Analyze a repository and compute the Technical Debt Ratio.

codesteward audit --target .
codesteward audit --target ./backend --json

What it reports

  • TDR – overall technical debt ratio.
  • cost_index – estimated remediation effort.
  • velocity_debt – risk of slowing development.
  • status – green/yellow/orange/red recommendation.
  • smells – counts and categories of detected AI-smells.

TDR interpretation

  • 0.0–0.3 — green: safe to repair automatically.
  • 0.31–0.6 — yellow: review recommended.
  • 0.61–0.8 — orange: verify carefully.
  • 0.81–1.0 — red: avoid automatic remediation without manual review.

codesteward fix

Generate and apply a remediation plan.

codesteward fix --target .
codesteward fix --target . --auto

How it works

  • Builds an ordered fix plan from AI-smell data.
  • Applies changes inside a shadow workspace.
  • Runs verification checks.
  • Writes verified patch data to ~/.codesteward/last-fix.json.

Modes

  • Interactive: prompts before applying changes.
  • --auto: apply the plan without confirmation.

codesteward status

Show the repository health dashboard.

codesteward status --target .

Dashboard includes

  • Current TDR and status
  • Smell trends
  • Verification confidence
  • Fix success rate

codesteward pr

Create a pull request from the last verified fix.

codesteward pr
codesteward pr --base main --title "Fix AI-generated debt" --draft

Prerequisites

  • ~/.codesteward/last-fix.json exists.
  • GitHub remote is configured.
  • gh CLI installed or GITHUB_TOKEN / GH_TOKEN available.
  • Branch state is clean.

Example output

✅ Pull request created: https://github.com/codesteward/codesteward/pull/123
✔️ Generated by Code-Steward local AI steward.

How It Works

Code-Steward is a local-first, four-stage workflow:

flowchart TB
  A[Audit] --> B[Plan]
  B --> C[Execute]
  C --> D[Verify]
  D --> E[PR]
  subgraph Local-Only
    F[Ollama + DeepSeek-R1]
  end
  A --> F
  B --> F
  C --> F
  D --> F
Loading

Architecture summary

  • Audit detects AI-smells and computes TDR.
  • Plan creates a repair sequence based on risk and scope.
  • Execute applies fixes in an isolated shadow workspace.
  • Verify ensures tests and behavior remain stable.
  • PR pushes the result as a review-ready pull request.

Local-first philosophy

Code-Steward keeps analysis and inference on your machine. No external LLM API calls are required, and no repository data is sent to the cloud unless you push a pull request through GitHub.

For full architecture details, see ARCHITECTURE.md.

Documentation Hub

Document Description
DEVELOPER_GUIDE.md Build, test, and extend the Code-Steward platform.
ARCHITECTURE.md System design, agents, and data flow.
AI_SMELLS_REFERENCE.md AI-smell taxonomy and detection heuristics.
TDR_EXPLAINER.md How Technical Debt Ratio is computed and used.
PR_GENERATION.md codesteward pr workflow and GitHub integration.
CONTRIBUTING.md Contribution process, bot guidelines, and community norms.

Community & Contributing

Help shape the public launch by contributing fixes, docs, test cases, and new smell rules.

  • Read the contribution guide: CONTRIBUTING.md
  • Report bugs or suggest new features on GitHub.
  • Review Steward Bot feedback and improve automation.
  • Grow from Contributor to Reviewer to Maintainer.

Steward Bot

The Steward Bot runs in CI/CD to inspect PRs, report TDR before and after, and guard against unsafe automated changes. If the bot blocks a PR, update the remediation and push again.

Join the conversation

  • GitHub Discussions: https://github.com/codesteward/codesteward/discussions
  • Issues: https://github.com/codesteward/codesteward/issues

Launch Call to Action

If Code-Steward helped you reduce risk, please star the repo and share the launch.

  • Star us ⭐ if you find the tool useful.
  • Share on X/Twitter: https://twitter.com/intent/tweet?text=Check+out+Code-Steward+%E2%80%94+local+AI+technical+debt+remediation
  • Share on LinkedIn: https://www.linkedin.com/sharing/share-offsite/?url=https://github.com/codesteward/codesteward

Join the 50 beta developers who already reduced their TDR by 30%.

License

License

Code-Steward is released under the terms of the project license. See LICENSE for details.

About

A local-first CLI that detects AI-generated technical debt, calculates remediation risk, and executes safe repair plans for developer-owned repositories.

Resources

Readme

Contributing

Contributing
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Sponsor this project

Packages

 
 
 

Contributors

Languages