# RepoMoss

RepoMoss 🌱 — You Build What's Next. RepoMoss Tends to What You've Left Behind.

Every developer knows the feeling.

You finish a feature, fix a bug, merge a pull request, and move on to the next exciting thing. But somewhere in your repository, small things start piling up.

• A broken link in the README.
• A TODO comment that has been sitting there for months.
• Documentation that needs attention.
• Small maintenance tasks that never feel urgent enough to prioritize.

Individually, these problems seem harmless. Over time, they make a codebase harder to understand and maintain.

For the DEV Community Hacktoberfest Challenge Week 3 — “Slow and Steady,” I built RepoMoss, a local-first AI-assisted codebase maintenance tool designed to help developers take care of these neglected tasks in small, controlled steps.

🔗 GitHub Repository: https://github.com/NiranjanRSoorej06/RepoMoss

🌱 What is RepoMoss?

RepoMoss scans a Git repository for a limited set of maintenance issues, organizes findings into a reviewable queue, and can attempt a narrow documentation repair in an isolated Git worktree.

The idea is simple:

Instead of waiting for a developer to notice every small maintenance problem, help them discover and address those problems before they accumulate.

RepoMoss isn't designed to replace developers or autonomously rewrite entire codebases. It focuses on small, evidence-backed tasks that can be inspected and verified.

✨ What can it do today?

The current MVP includes:

1. Repository validation

Register a local Git repository and inspect its branch, commit, and working-tree state before scanning.

2. Maintenance scanning

Detect TODO, FIXME, and XXX markers in Markdown files, along with broken relative links in Markdown documentation.

3. Evidence-backed findings

Each finding includes its file references, relevant evidence, category, priority, risk, and a proposed plan. Findings are surfaced for review rather than blindly treated as defects.

4. Optional local AI explanations

RepoMoss can use a model served through Ollama to explain findings. If Ollama is unavailable, a deterministic fallback keeps the core workflow usable.

5. Human-controlled execution

Review a finding and explicitly approve an attempt before RepoMoss starts working on it. Findings can also be deferred or rejected.

6. Isolated documentation repair

For a supported broken-link case, RepoMoss can attempt a bounded repair in a separate Git worktree instead of editing your original checkout.

7. Controlled verification and reporting

Verification commands must be explicitly configured by the operator and must match the configured allowlist. RepoMoss records the resulting diff, logs, and report so developers can inspect what happened.

The important distinction is that a generated plan or patch is not automatically a successful fix. Actual results and verification output matter.

🧠 Why use open-weight AI?

For RepoMoss, open-weight AI is about more than generating explanations.

It gives developers the flexibility to run compatible models locally, choose a model that suits their hardware and requirements, and avoid sending repository evidence to a hosted inference API by default.

RepoMoss is designed around local-first operation:

• Repository scanning happens locally.
• SQLite stores task and scan history locally.
• Optional model explanations use Ollama.
• Repository evidence is not sent to a hosted inference API by RepoMoss.
• The core scanner can work without a model connection.

This matters for personal projects, student repositories, and private codebases where developers may prefer to keep their work on their own machines.

Open-weight models also make experimentation more accessible. Developers can explore different models and trade-offs without having to redesign the entire maintenance workflow around a single hosted AI provider.

Of course, local inference still consumes hardware resources, and open weights do not automatically mean that every part of a model's training process or licensing is fully open source.

🛡️ Safety is part of the design

An AI maintenance tool should not be trusted simply because it sounds confident.

RepoMoss follows a deliberately constrained approach:

• No automatic merging: it never merges or pushes changes.
• No edits to the original checkout: attempted changes are kept in a separate Git worktree.
• Explicit approval: a task must be approved before an attempt begins.
• No model-generated shell commands: the model explains findings but cannot issue commands or provide executable patches in this MVP.
• Opt-in verification: no verification commands run by default.
• Bounded scanning: common dependency and build directories, symlinks, likely secrets, oversized files, and excessive file counts are handled conservatively.
• Transparent outcomes: diffs, logs, and reports help developers review the attempt.

These protections reduce risk, but they are not a substitute for a proper operating-system sandbox. Git worktrees isolate changes from the original checkout; they do not make arbitrary repository code safe to execute. Verification commands should therefore be configured carefully.

🛠️ Tech stack

RepoMoss currently uses:

• Python + FastAPI for the backend and API.
• HTML, CSS, and JavaScript for the lightweight dashboard.
• SQLite for local persistence.
• Git and Git worktrees for repository inspection and isolated changes.
• Ollama for optional local model inference.
• Pydantic for structured data and validation.

The architecture intentionally keeps the core maintenance workflow useful even when the optional model service is unavailable.

🔄 How the workflow works

The core workflow follows a simple sequence:

1. Register a local Git repository.
2. Scan for supported maintenance issues.
3. Review the findings and their evidence.
4. Request an optional local-model explanation.
5. Approve a suitable task.
6. Attempt the supported repair in an isolated worktree.
7. Optionally run explicitly allowlisted verification commands.
8. Review the diff, logs, and Markdown report.

The goal isn't to make maintenance completely invisible. It is to make it easier to start, easier to review, and less likely to be forgotten.

🚧 Current limitations and what's next

RepoMoss is an MVP, not a fully autonomous coding agent.

Currently, its scanner focuses on a small set of Markdown maintenance issues. TODO findings are available for review but are not automatically patched. The supported repair is deliberately narrow: converting a broken local Markdown link into its visible plain-text label.

Broader code repairs, automatic test generation, scheduled maintenance, cancellation, automatic merging, and OS-level sandboxing are not implemented.

Future improvements could include:

• More deterministic maintenance checks.
• Additional safe documentation repairs.
• Better repository-specific verification profiles.
• Richer maintenance reports and historical trends.
• More evaluation across real-world repositories.
• Additional model options and configurable task policies.

I'd rather build a small tool that clearly reports what it did than a broad agent that claims success without enough evidence.

💚 Why this project fits “Slow and Steady”

The theme resonates with the problem RepoMoss is trying to solve.

Software maintenance rarely consists of one dramatic moment. It is a collection of small decisions and small tasks repeated over time.

RepoMoss applies that philosophy to both the problem and the solution: find manageable tasks, attempt them in isolation, verify what happened, and leave the final decision with the developer.

It also reflects why open innovation matters to me. Local models, accessible tooling, and open repositories give developers room to experiment with different approaches instead of depending entirely on a closed service.

The result is not an AI that takes control of your repository. It is a tool that helps you pay attention to the parts of your project that are easy to overlook.

🙌 Try it out

The project is available here:

🔗 Repository: https://github.com/NiranjanRSoorej06/RepoMoss

The README contains local setup instructions, verification configuration, security notes, and the current MVP feature list.

If you try RepoMoss, I'd love feedback on which maintenance checks would be most useful, what safety controls you would want before trusting an automated repair, and how you would evaluate whether a maintenance assistant is genuinely helping.

You build what's next. RepoMoss tends to what you've left behind. 🌱