[RFC] The AutoMaintainer CLI

[purvanshjoshi]

[RFC] The AutoMaintainer CLI (automaintainer)

The Vision

The web dashboard is excellent for remote observability, but software engineering happens natively on the local filesystem. We propose building a native Command Line Interface (CLI) that brings the AutoMaintainer 5-agent LangGraph pipeline directly to the developer's terminal.

This will allow developers to execute autonomous refactors, bug fixes, and architectural reviews on their uncommitted, local code without relying on the GitHub REST API.

Proposed Architecture

The CLI will be built using Python's Click or argparse libraries. It will operate completely headless, invoking the LangGraph state machine directly and streaming the execution logs to stdout.

flowchart LR
    classDef input fill:#2d3748,stroke:#4a5568,stroke-width:2px,color:#fff,rx:8px
    classDef cli fill:#2b6cb0,stroke:#2c5282,stroke-width:2px,color:#fff,rx:8px
    classDef engine fill:#276749,stroke:#22543d,stroke-width:2px,color:#fff,rx:8px
    classDef indexer fill:#744210,stroke:#5f370e,stroke-width:2px,color:#fff,rx:8px

    User(["Developer Terminal"]):::input
    
    subgraph LocalEnvironment [Local Machine Execution]
        direction TB
        CLI["CLI Entrypoint\n(automaintainer run)"]:::cli
        GraphEngine["LangGraph Engine\n(Headless Pipeline)"]:::engine
        GitNexus["GitNexus Binary\n(Local File Indexer)"]:::indexer
    end

    User -->|Executes command| CLI
    CLI -->|Initializes Context| GraphEngine
    GraphEngine <-->|Queries semantic codebase| GitNexus
    GraphEngine -->|Streams stdout| User

Loading

Proposed Commands

1. automaintainer init
   • Configures local .env with Groq API keys and initializes a .automaintainer configuration folder in the current repository.
2. automaintainer run <prompt>
   • Bypasses GitHub Issues. Triggers the Implementer agent directly to execute code changes based on the prompt.
   • Example: $ automaintainer run "Refactor the authentication logic to use JWT"
3. automaintainer review
   • Analyzes all uncommitted Git changes in the working directory. The Reviewer agent provides immediate architectural feedback in the terminal before the developer commits.
4. automaintainer architect
   • The Architect scans the repository and outputs a markdown summary of the codebase's structural health and technical debt.

Distribution Strategy

The CLI will be distributed via PyPI (pip install automaintainer).

Open Questions

1. How do we visually represent the 5-agent workflow in the terminal? Should we use a rich UI library like Rich or Textual to render a live dashboard in the console?
2. Should the CLI automatically commit the changes, or should it leave the files in a modified state for the developer to manually review using git diff before committing?

Please leave your thoughts and architectural feedback below!