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 runs a continuous improvement loop: McGr
Add this skill
npx mdskills install tigranbs/mcgravityWell-documented TUI tool for orchestrating AI coding assistants with atomic task breakdown
1# McGravity23<div align="center">4 <img src="https://raw.githubusercontent.com/tigranbs/mcgravity/main/assets/thumbnail.png" alt="McGravity Thumbnail" width="400">5</div>67**Fast, opinionated TUI for AI-assisted coding.**89McGravity 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.1011```12+------------------------------------------------------------+13| McGravity [Claude Code] |14+--------------------------- Output -------------------------+15| > Planning complete |16| > Executing task-001.md... |17| + Created src/auth/login.rs |18| + Updated src/main.rs |19+------------------------------------------------------------+20| Iteration #1 | Executing | task-001.md |21+------------------------------------------------------------+22| [##########-----] 1/3 tasks |23+--------------------------- Task ---------------------------+24| Add user authentication with JWT tokens. |25| Reference @src/auth/ for existing patterns. |26+------------------------------------------------------------+27| [Esc] Cancel [Ctrl+S] Settings |28+------------------------------------------------------------+29```3031## How It Works3233McGravity runs a continuous improvement loop:3435```mermaid36flowchart LR37 A[Your Task] --> B[Plan]38 B --> C[Execute]39 C --> D{Done?}40 D -->|More work needed| B41 D -->|Complete| E[Finished]42```4344## Quick Start4546### 1. Install McGravity4748```bash49# bun, npm, pnpm, yarn, etc.50npm install -g mcgravity51```5253### 2. Install an AI CLI5455McGravity needs at least one AI coding tool installed:5657| Tool | Install Command | Documentation |58| --------------- | ------------------------------------------ | -------------------------------------------- |59| **Claude Code** | `npm install -g @anthropic-ai/claude-code` | [claude.ai/code](https://claude.ai/code) |60| **Codex** | `npm install -g @openai/codex` | [openai.com/codex](https://openai.com/codex) |61| **Gemini CLI** | `npm install -g @google/gemini-cli` | [ai.google.dev](https://ai.google.dev) |6263### 3. Run McGravity6465```bash66cd your-project67mcgravity68```6970On first run, McGravity will detect available AI tools and ask you to choose which to use for planning and execution.7172### 4. Describe Your Task7374Type what you want to build or fix:7576```77Add a /health endpoint that returns JSON with status and uptime.78Check @src/routes/ for existing patterns.79```8081Press `Enter` to start the flow.8283## Installation Options8485### Install Script (Recommended)8687The install script automatically detects your OS and architecture:8889```bash90# bun, npm, pnpm, yarn, etc.91npm install -g mcgravity92```9394### GitHub Releases9596Download the latest release for your platform from [GitHub Releases](https://github.com/tigranbs/mcgravity/releases), extract, and add to your PATH.9798### Build from Source99100```bash101git clone https://github.com/tigranbs/mcgravity.git102cd mcgravity103cargo install --path .104```105106## Usage Guide107108### Writing Task Descriptions109110Good task descriptions are specific and reference relevant files:111112```113Add input validation to the user registration form.114- Email must be valid format115- Password minimum 8 characters116- Show error messages inline117Check @src/components/RegisterForm.tsx for the component.118```119120**Tips:**121122- Be specific about what you want123- Reference files with `@` mentions124- List acceptance criteria125- Mention constraints (e.g., "don't add new dependencies")126127### @ File Mentions128129Type `@` followed by a filename to search your project:130131```132Update @src/config.ts to add the new API endpoint.133```134135- **Fuzzy search**: `@config` finds `src/config.ts`136- **Navigation**: Use `Up/Down` or `j/k` to select137- **Insert**: Press `Tab` or `Enter` to insert the path138- **Cancel**: Press `Esc` to dismiss139140Files matching `.gitignore` patterns are excluded from suggestions.141142### Slash Commands143144Type `/` at the start of a line to see available commands:145146| Command | Description |147| ----------- | ---------------------------------- |148| `/settings` | Open settings panel |149| `/clear` | Clear task, output, and todo files |150| `/exit` | Exit McGravity |151152### Settings153154Press `Ctrl+S` to open settings:155156| Setting | Options | Description |157| ------------------- | ---------------------- | ------------------------------- |158| **Planning Model** | Claude, Codex, Gemini | AI tool for breaking down tasks |159| **Execution Model** | Claude, Codex, Gemini | AI tool for implementing tasks |160| **Enter Behavior** | Submit / Newline | What `Enter` does in the input |161| **Max Iterations** | 1, 3, 5, 10, Unlimited | How many plan→execute cycles |162163Settings are saved automatically to `.mcgravity/settings.json`.164165## Key Bindings166167### Global168169| Key | Action |170| -------- | ------------------------------------ |171| `Ctrl+S` | Open settings |172| `Ctrl+C` | Quit |173| `Esc` | Cancel running flow / Quit when idle |174175### Text Input176177| Key | Action |178| ------------- | ------------------------------------------------ |179| `Enter` | Submit task (default) or newline (if configured) |180| `Ctrl+Enter` | Always submits |181| `Ctrl+J` | Always inserts newline (works on all terminals) |182| `Shift+Enter` | Insert newline |183| `@` | Open file search |184| `/` | Open command menu (at line start) |185186### Output Panel187188| Key | Action |189| ----------------- | ------------------ |190| `Ctrl+Up/Down` | Scroll output |191| `PageUp/PageDown` | Page scroll |192| `Ctrl+Home/End` | Jump to top/bottom |193194### Settings Panel195196| Key | Action |197| ------------------ | ---------------- |198| `Up/Down` or `j/k` | Navigate options |199| `Enter` or `Space` | Change selection |200| `Esc` or `q` | Close settings |201202### The Flow in Detail203204```mermaid205flowchart TD206 subgraph Input207 A[Write task description]208 end209210 subgraph Planning["Planning Phase"]211 B[AI reads your codebase]212 C[AI creates atomic task files]213 B --> C214 end215216 subgraph Execution["Execution Phase"]217 D[Pick next task file]218 E[AI implements the task]219 F[Move to done folder]220 D --> E --> F221 end222223 subgraph Review["Review Cycle"]224 G{More tasks?}225 H{More work needed?}226 end227228 A --> B229 C --> G230 G -->|Yes| D231 G -->|No| I[Complete]232 F --> G233 G -->|All done| H234 H -->|Yes| B235 H -->|No| I236```237238**Why this approach?**2392401. **Focused AI**: Each phase has a single job. The planner only plans. The executor only executes.2412. **Atomic tasks**: Small, verifiable changes. Easy to review, easy to fix if something goes wrong.2423. **Built-in context**: Completed tasks inform the next planning cycle, so the AI knows what's been done.2434. **Controllable**: Cancel anytime with `Esc`. Set max iterations. Review after each cycle.244245## File Structure (generated by McGravity)246247McGravity creates a `.mcgravity/` folder in your project:248249```250.mcgravity/251├── settings.json # Your preferences252├── task.md # Current task + completed task references253└── todo/254 ├── task-001.md # Pending task (created by planner)255 ├── task-002.md # Pending task256 └── done/257 └── task-001.md # Completed task (archived)258```259260### Task Files261262Each task file contains:263264```markdown265# Task 001: Add health endpoint266267## Objective268269Create a /health endpoint returning JSON status.270271## Implementation Steps2722731. Create route handler in src/routes/health.rs2742. Return JSON with status and uptime fields2753. Register route in src/main.rs276277## Reference Files278279- src/routes/mod.rs - Add module export280- src/main.rs - Register route281282## Acceptance Criteria283284- [ ] GET /health returns 200285- [ ] Response includes "status" and "uptime" fields286```287288## Troubleshooting289290### No AI tools detected291292McGravity requires at least one AI CLI tool. Install one:293294```bash295npm install -g @anthropic-ai/claude-code # Claude Code296npm install -g @openai/codex # Codex297npm install -g @google/gemini-cli # Gemini298```299300Then restart McGravity.301302### Keys not working as expected303304Some terminals don't report modifier keys correctly. Try:305306- Use `Ctrl+J` for newlines (works everywhere)307- Use `j/k` instead of arrow keys for navigation308309Enable debug mode to see what your terminal sends:310311```bash312MCGRAVITY_DEBUG_KEYS=1 mcgravity313```314315### Multi-line input316317Several methods to insert newlines:318319| Method | How |320| ---------------- | --------------------------------- |321| `Ctrl+J` | Works on all terminals |322| `Shift+Enter` | Standard (may not work on iPad) |323| `\` then `Enter` | Backslash escape |324| Settings | Set "Enter Behavior" to "Newline" |325326### Flow not progressing3273281. Check the output panel for error messages3292. Verify your AI CLI is authenticated (`claude --help`, `codex --help`)3303. Try reducing max iterations to 1 for debugging3314. Cancel with `Esc` and try a simpler task332333## Privacy334335McGravity 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.336337## License338339MIT340341---342343**Built with Rust + Ratatui** by [@tigranbs](https://github.com/tigranbs)344345[Report Issues](https://github.com/tigranbs/mcgravity/issues) · [Releases](https://github.com/tigranbs/mcgravity/releases)346
Full transparency — inspect the skill content before installing.