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:

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

Quick Start

$3

`bash


bun, npm, pnpm, yarn, etc.


npm install -g mcgravity
`

$3

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

`bash
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.

$3

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

$3

The install script automatically detects your OS and architecture:

`bash


bun, npm, pnpm, yarn, etc.


npm install -g mcgravity
`

$3

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

$3

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

Usage Guide

$3

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")

$3

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.

$3

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 |

$3

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

$3

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

$3

| 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) |

$3

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

$3

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

$3

`mermaid
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?

1. Focused AI: Each phase has a single job. The planner only plans. The executor only executes.
2. Atomic tasks: Small, verifiable changes. Easy to review, easy to fix if something goes wrong.
3. Built-in context: Completed tasks inform the next planning cycle, so the AI knows what's been done.
4. 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)
`

$3

Each task file contains:

`markdown


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

$3

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

`bash
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.

$3

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:

`bash
MCGRAVITY_DEBUG_KEYS=1 mcgravity
`

$3

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" |

$3

1. Check the output panel for error messages
2. Verify your AI CLI is authenticated (claude --help, codex --help)
3. Try reducing max iterations to 1 for debugging
4. 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