TurboDev

Terminal-based AI coding agent — your coding partner in the terminal.

What is it

TurboDev is an AI coding agent that runs entirely in the terminal. It lets you chat with LLM models (via OpenRouter), execute tools, manage files and code — all without leaving the CLI.

Documentation: https://rosmoscato.xyz/turbodev/

Features

• AI Chat in the terminal — converse with LLM models in real time with streaming
• Model selection — choose from dozens of popular models (DeepSeek, GPT-4, Claude, Gemini, Llama, GLM...)
• Multi-agent system — switch between specialized agents (editor, plan) with a single keypress, or create custom agents via Markdown
• Permission system — fine-grained control over what agents can do (allow, ask, deny) with bash glob patterns
• 10 built-in tools — the AI can read, search, and edit files, run shell commands, ask questions, invoke subagents, and perform Git/GitHub operations
• Git integration — 26 Git operations via simple-git, accessible through slash commands and AI tools
• GitHub integration — 15 GitHub operations via gh CLI, including PR management and authentication wizard
• Command palette — type / to browse all commands alphabetically with arrow key navigation
• @ file/folder referencing — type @ to reference files or folders in your message; the content is included as context for the AI
• Session persistence — conversations are saved automatically and can be resumed across restarts
• Context window management — real-time token tracking (0.56K/128K), auto-compaction at 85%, manual /compact
• Real-time cost tracking — see how much you're spending per session based on OpenRouter pricing
• Agent Skills — extend agent capabilities with installable skill packs (.agents/skills/), following the open Agent Skills specification
• MCP support — connect external tool servers via the Model Context Protocol (stdio transport, tools primitive)
• Persistent memory — the AI remembers your preferences, decisions, and project facts across sessions (.turbodev/memory.md)
• Economy mode — cut token usage ~50-70% with concise output mode (/economy eco|ultra)
• Request interruption — press Escape to cancel a running AI request at any time
• AGENTS.md support — project context and instructions loaded automatically from the open standard
• /init wizard — generate an AGENTS.md file interactively with auto-detection of project type
• Markdown rendering — formatted responses with headings, lists, code blocks, and bold text in the terminal
• Guided setup — interactive configuration of API key and model on first launch
• Git status in status bar — current branch, dirty count, and ahead/behind indicators

Installation

# Install globally via npm
npm install -g @rosariomoscato/turbodev

# Or run directly without installing
npx @rosariomoscato/turbodev

From Source

git clone https://github.com/rosariomoscato/TurboDev.git
cd TurboDev
npm install
npm run build
npm link

Usage

# Launch TurboDev in the current directory
turbodev

# Launch in a specific directory
turbodev --cwd /path/to/project

# Guided setup
turbodev --setup

Chat commands

Type / to open the command palette, or type commands directly:

| Command | Description | |---------|-------------| | /agent | Switch agent | | /clear | Clear chat history | | /compact | Compact conversation to free context window | | /exit | Exit TurboDev | | /help | Show available commands | | /init | Generate AGENTS.md with interactive wizard | | /model | Select AI model | | /new | Start a new session | | /sessions | List and switch between sessions | | /setup | Re-run setup wizard | | /skills | List discovered agent skills | | /mcp | List MCP servers and tools | | /mcp reload | Re-read .turbodev/mcp.json and reconnect | | /memory | Show persistent memory entries | | /memory add [cat] <text> | Add a memory entry (categories: preferences, decisions, architecture, facts) | | /memory clear [cat] | Clear all or one category of memory | | /memory reload | Reload memory from disk | | /economy | Show economy mode status | | /economy eco | Activate concise output (direct, no filler) | | /economy ultra | Activate ultra-concise output (telegraphic) | | /economy off | Deactivate economy mode |

Git commands

| Command | Description | |---------|-------------| | /branch | List branches | | /branch <name> | Switch branch | | /commit <msg> | Stage all and commit | | /git add | Stage files (default: all) | | /git diff | Show unstaged changes | | /git log | Show commit log | | /git remote | List remotes | | /git stash | Stash changes | | /git status | Show working tree status | | /pull | Pull from remote | | /push | Push to remote | | /rollback | Show recent commits to revert |

GitHub commands

| Command | Description | |---------|-------------| | /gh auth | GitHub authentication wizard | | /pr <title> | Create a pull request | | /pr list | List pull requests |

Keyboard shortcuts

| Key | Action | |-----|--------| | / | Open command palette | | Tab | Switch between agents | | Escape | Cancel action / Interrupt AI request | | @agentname | Invoke an agent directly | | @path | Reference a file or folder (e.g. @src/App.tsx) |

Available tools

| Tool | Description | |------|-------------| | bash | Execute shell commands with timeout | | edit_file | Create or edit a file | | git | Execute Git operations (status, log, diff, add, commit, push, pull, branch, stash, remote, and more) | | github | Execute GitHub operations (create PR, list PRs, create issue, list issues, create release, and more) | | grep | Search file contents with regex (uses ripgrep if available) | | list_files | List files in a directory | | mkdir | Create directories | | question | Ask the user for clarification | | read_file | Read the contents of a file | | load_skill | Load skill instructions or resource files | | save_memory | Save a durable fact to persistent memory for future sessions | | task | Invoke a subagent for specialized tasks |

Configuration

TurboDev requires an OpenRouter API key to work. The setup wizard will guide you through configuration on first launch, or you can launch it with /setup.

Configuration is saved in ~/.config/turbodev/config.json.

GitHub Authentication

To use GitHub features, authenticate with:

/gh auth

This opens an interactive wizard that supports browser-based login or personal access token. Requires the GitHub CLI (gh) to be installed.

MCP (Model Context Protocol)

TurboDev supports connecting external tool servers via the Model Context Protocol (MCP). Servers are declared in .turbodev/mcp.json (Claude Desktop-compatible format):

{
  "mcpServers": {
    "filesystem": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-filesystem", "/path/to/dir"]
    }
  }
}

At startup TurboDev spawns each server via stdio, lists its tools, and registers them with prefixed names (mcp__<server>__<tool>) so the LLM can call them like native tools. Environment variables ($VAR, ${VAR}) and ~ in the config are expanded.

Permissions: MCP tools default to ask — the user approves the first call per server. Override per-server in agent Markdown:

permission:
  mcp: { filesystem: allow, github: ask }

Use /mcp to inspect server status and /mcp reload to reconnect after config changes. A growing list of MCP servers is available at github.com/modelcontextprotocol/servers.

AGENTS.md

TurboDev supports the open AGENTS.md standard — a markdown file that provides context and instructions to the AI agent. If present in the working directory, it is automatically loaded at startup and passed as project context.

The /init command generates the file through an interactive wizard that:

• Auto-detects the project type (Node.js, Python, Rust, Go)
• Lets you select which sections to include (Setup Commands, Code Style, Testing, Design, etc.)
• If the file already exists, asks whether to overwrite or append new sections

Roadmap

Starting June 2026, we ship a new feature every week:

| Week | Feature | Description | |------|---------|-------------| | Jun 11 | Skills ✅ | Installable skill packs that extend agent capabilities | | Jun 18 | MCP ✅ | Model Context Protocol support for external tool integration | | Jun 25 | Persistent Memory ✅ | Cross-session memory so the AI remembers your project context | | Jul 2 | Economy Mode ✅ | Budget-aware mode that optimizes token usage and model selection | | Jul 9 | Ollama Connection | Run local models via Ollama alongside OpenRouter |

Tech Stack

• TypeScript — primary language
• React + Ink — declarative terminal UI
• OpenRouter — multi-model LLM provider
• simple-git — Git operations
• gh CLI — GitHub integration
• tsup — build system

Author

Rosario Moscato

License

This work is licensed under Creative Commons Attribution-NonCommercial-ShareAlike 4.0 International.

You are free to:

• Share — copy and redistribute the material in any medium or format
• Adapt — remix, transform, and build upon the material

Under the following terms:

• Attribution — you must give appropriate credit to the author
• NonCommercial — you may not use the material for commercial purposes
• ShareAlike — if you remix or transform, you must distribute under the same license