McGravity

Fast, opinionated TUI for AI-assisted coding.

McGravity orchestrates AI coding tools (Claude Code, Codex, Gemini) in a tight feedback loop: plan small tasks → execute one at a time → review → replan. Instead of dumping a huge prompt and hoping for the best, McGravity breaks your work into atomic pieces that are easier to verify and course-correct.

+------------------------------------------------------------+
| McGravity                                    [Claude Code] |
+--------------------------- Output -------------------------+
| > Planning complete                                        |
| > Executing task-001.md...                                 |
| + Created src/auth/login.rs                                |
| + Updated src/main.rs                                      |
+------------------------------------------------------------+
| Iteration #1 | Executing | task-001.md                    |
+------------------------------------------------------------+
| [##########-----] 1/3 tasks                                |
+--------------------------- Task ---------------------------+
| Add user authentication with JWT tokens.                   |
| Reference @src/auth/ for existing patterns.                |
+------------------------------------------------------------+
| [Esc] Cancel  [Ctrl+S] Settings                            |
+------------------------------------------------------------+

How It Works

McGravity runs a continuous improvement loop:

flowchart LR
    A[Your Task] --> B[Plan]
    B --> C[Execute]
    C --> D{Done?}
    D -->|More work needed| B
    D -->|Complete| E[Finished]

Quick Start

1. Install McGravity

# bun, npm, pnpm, yarn, etc.
npm install -g mcgravity

2. Install an AI CLI

McGravity needs at least one AI coding tool installed:

| Tool | Install Command | Documentation | | --------------- | ------------------------------------------ | -------------------------------------------- | | Claude Code | npm install -g @anthropic-ai/claude-code | claude.ai/code | | Codex | npm install -g @openai/codex | openai.com/codex | | Gemini CLI | npm install -g @google/gemini-cli | ai.google.dev |

3. Run McGravity

cd your-project
mcgravity

On first run, McGravity will detect available AI tools and ask you to choose which to use for planning and execution.

4. Describe Your Task

Type what you want to build or fix:

Add a /health endpoint that returns JSON with status and uptime.
Check @src/routes/ for existing patterns.

Press Enter to start the flow.

Installation Options

Install Script (Recommended)

The install script automatically detects your OS and architecture:

# bun, npm, pnpm, yarn, etc.
npm install -g mcgravity

GitHub Releases

Download the latest release for your platform from GitHub Releases, extract, and add to your PATH.

Build from Source

git clone https://github.com/tigranbs/mcgravity.git
cd mcgravity
cargo install --path .

Usage Guide

Writing Task Descriptions

Good task descriptions are specific and reference relevant files:

Add input validation to the user registration form.
- Email must be valid format
- Password minimum 8 characters
- Show error messages inline
Check @src/components/RegisterForm.tsx for the component.

Tips:

Be specific about what you want
Reference files with @ mentions
List acceptance criteria
Mention constraints (e.g., "don't add new dependencies")

@ File Mentions

Type @ followed by a filename to search your project:

Update @src/config.ts to add the new API endpoint.

Fuzzy search: @config finds src/config.ts
Navigation: Use Up/Down or j/k to select
Insert: Press Tab or Enter to insert the path
Cancel: Press Esc to dismiss

Files matching .gitignore patterns are excluded from suggestions.

Slash Commands

Type / at the start of a line to see available commands:

| Command | Description | | ----------- | ---------------------------------- | | /settings | Open settings panel | | /clear | Clear task, output, and todo files | | /exit | Exit McGravity |

Settings

Press Ctrl+S to open settings:

| Setting | Options | Description | | ------------------- | ---------------------- | ------------------------------- | | Planning Model | Claude, Codex, Gemini | AI tool for breaking down tasks | | Execution Model | Claude, Codex, Gemini | AI tool for implementing tasks | | Enter Behavior | Submit / Newline | What Enter does in the input | | Max Iterations | 1, 3, 5, 10, Unlimited | How many plan→execute cycles |

Settings are saved automatically to .mcgravity/settings.json.

Key Bindings

Global

| Key | Action | | -------- | ------------------------------------ | | Ctrl+S | Open settings | | Ctrl+C | Quit | | Esc | Cancel running flow / Quit when idle |

Text Input

| Key | Action | | ------------- | ------------------------------------------------ | | Enter | Submit task (default) or newline (if configured) | | Ctrl+Enter | Always submits | | Ctrl+J | Always inserts newline (works on all terminals) | | Shift+Enter | Insert newline | | @ | Open file search | | / | Open command menu (at line start) |

Output Panel

| Key | Action | | ----------------- | ------------------ | | Ctrl+Up/Down | Scroll output | | PageUp/PageDown | Page scroll | | Ctrl+Home/End | Jump to top/bottom |

Settings Panel

| Key | Action | | ------------------ | ---------------- | | Up/Down or j/k | Navigate options | | Enter or Space | Change selection | | Esc or q | Close settings |

The Flow in Detail

flowchart TD
    subgraph Input
        A[Write task description]
    end

    subgraph Planning["Planning Phase"]
        B[AI reads your codebase]
        C[AI creates atomic task files]
        B --> C
    end

    subgraph Execution["Execution Phase"]
        D[Pick next task file]
        E[AI implements the task]
        F[Move to done folder]
        D --> E --> F
    end

    subgraph Review["Review Cycle"]
        G{More tasks?}
        H{More work needed?}
    end

    A --> B
    C --> G
    G -->|Yes| D
    G -->|No| I[Complete]
    F --> G
    G -->|All done| H
    H -->|Yes| B
    H -->|No| I

Why this approach?

Focused AI: Each phase has a single job. The planner only plans. The executor only executes.
Atomic tasks: Small, verifiable changes. Easy to review, easy to fix if something goes wrong.
Built-in context: Completed tasks inform the next planning cycle, so the AI knows what's been done.
Controllable: Cancel anytime with Esc. Set max iterations. Review after each cycle.

File Structure (generated by McGravity)

McGravity creates a .mcgravity/ folder in your project:

.mcgravity/
├── settings.json      # Your preferences
├── task.md            # Current task + completed task references
└── todo/
    ├── task-001.md    # Pending task (created by planner)
    ├── task-002.md    # Pending task
    └── done/
        └── task-001.md    # Completed task (archived)

Task Files

Each task file contains:

# Task 001: Add health endpoint

## Objective

Create a /health endpoint returning JSON status.

## Implementation Steps

1. Create route handler in src/routes/health.rs
2. Return JSON with status and uptime fields
3. Register route in src/main.rs

## Reference Files

- src/routes/mod.rs - Add module export
- src/main.rs - Register route

## Acceptance Criteria

- [ ] GET /health returns 200
- [ ] Response includes "status" and "uptime" fields

Troubleshooting

No AI tools detected

McGravity requires at least one AI CLI tool. Install one:

npm install -g @anthropic-ai/claude-code  # Claude Code
npm install -g @openai/codex               # Codex
npm install -g @google/gemini-cli          # Gemini

Then restart McGravity.

Keys not working as expected

Some terminals don't report modifier keys correctly. Try:

Use Ctrl+J for newlines (works everywhere)
Use j/k instead of arrow keys for navigation

Enable debug mode to see what your terminal sends:

MCGRAVITY_DEBUG_KEYS=1 mcgravity

Multi-line input

Several methods to insert newlines:

| Method | How | | ---------------- | --------------------------------- | | Ctrl+J | Works on all terminals | | Shift+Enter | Standard (may not work on iPad) | | \ then Enter | Backslash escape | | Settings | Set "Enter Behavior" to "Newline" |

Flow not progressing

Check the output panel for error messages
Verify your AI CLI is authenticated (claude --help, codex --help)
Try reducing max iterations to 1 for debugging
Cancel with Esc and try a simpler task

Privacy

McGravity runs AI CLI tools locally on your machine. It never collects, stores, or transmits your code or API keys. Configure authentication directly in the AI CLI tools you use.

License

MIT

---

Built with Rust + Ratatui by @tigranbs

Report Issues · Releases

mcgravity