Carlos Gutierrez
a47fbad320
README updates: - Add Copilot Usage Display section with features and color indicators - Update /usage command description to mention color-coded progress bars CHANGELOG updates (Unreleased): - Add Copilot Usage Display feature with quota monitoring - Add Enhanced /usage Command with colors - Add Session Resume fix for --resume functionality - Add resume link fix showing correct session ID
505 lines
14 KiB
Markdown
505 lines
14 KiB
Markdown
# CodeTyper CLI
|
|
|
|
<p align="center">
|
|
<img src="assets/Codetyper_logo.png" alt="CodeTyper Logo" width="400">
|
|
</p>
|
|
|
|
<p align="center">
|
|
<a href="https://github.com/CarGDev/codetyper.cli/releases"><img src="https://img.shields.io/badge/version-0.3.0-blue" alt="Version"></a>
|
|
<a href="https://github.com/CarGDev/codetyper.cli/blob/master/LICENSE"><img src="https://img.shields.io/badge/license-MIT-green" alt="License"></a>
|
|
<a href="https://bun.sh"><img src="https://img.shields.io/badge/runtime-Bun-orange" alt="Bun"></a>
|
|
</p>
|
|
|
|
An AI-powered terminal coding agent with an interactive TUI. CodeTyper autonomously executes coding tasks using tool calls with granular permission controls and intelligent provider routing.
|
|
|
|
## How It Works
|
|
|
|
CodeTyper is an autonomous coding agent that runs in your terminal. You describe what you want to build or fix, and CodeTyper:
|
|
|
|
1. **Analyzes** your request and breaks it into steps
|
|
2. **Executes** tools (bash, read, write, edit) to accomplish the task
|
|
3. **Asks permission** before modifying files or running commands
|
|
4. **Learns** from your project to provide context-aware assistance
|
|
|
|
### Cascading Provider System
|
|
|
|
CodeTyper uses an intelligent provider routing system:
|
|
|
|
```
|
|
User Request
|
|
|
|
|
v
|
|
[Detect Task Type] --> code_generation, bug_fix, refactoring, etc.
|
|
|
|
|
v
|
|
[Check Ollama Score] --> Quality score from past interactions
|
|
|
|
|
v
|
|
[Route Decision]
|
|
|
|
|
+-- High Score (85%+) --> Ollama Only (trusted)
|
|
|
|
|
+-- Low Score (40%-) --> Copilot Only (needs improvement)
|
|
|
|
|
+-- Medium Score --> Cascade Mode
|
|
|
|
|
v
|
|
[1. Ollama generates response]
|
|
|
|
|
v
|
|
[2. Copilot audits for issues]
|
|
|
|
|
v
|
|
[3. Update quality scores]
|
|
|
|
|
v
|
|
[Return best response]
|
|
```
|
|
|
|
Over time, CodeTyper learns which provider performs best for different task types.
|
|
|
|
## Installation
|
|
|
|
**Requires [Bun](https://bun.sh) runtime** (v1.0.0+)
|
|
|
|
```bash
|
|
# Install Bun if you don't have it
|
|
curl -fsSL https://bun.sh/install | bash
|
|
|
|
# Install globally via npm
|
|
npm install -g codetyper-cli
|
|
|
|
# Or install from source
|
|
git clone https://github.com/CarGDev/codetyper.cli.git
|
|
cd codetyper.cli
|
|
bun install && bun run build && bun link
|
|
|
|
# Login to a provider
|
|
codetyper login copilot
|
|
|
|
# Start interactive chat
|
|
codetyper
|
|
```
|
|
|
|
## Features
|
|
|
|
### Interactive TUI
|
|
|
|
Full-screen terminal interface with real-time streaming responses.
|
|
|
|
|
|
|
|
**Key bindings:**
|
|
|
|
- `Enter` - Send message
|
|
- `Shift+Enter` - New line
|
|
- `@` - Open file picker (works anywhere in input)
|
|
- `/` - Open command menu (works anywhere in input)
|
|
- `Ctrl+M` - Toggle interaction mode
|
|
- `Ctrl+T` - Toggle todo panel
|
|
- `Ctrl+O` - Toggle activity panel
|
|
- `Shift+Up/Down` - Scroll log panel
|
|
- `Ctrl+C` (twice) - Exit
|
|
|
|
### Vim Motions
|
|
|
|
Optional vim-style keyboard navigation for power users. Enable in settings.
|
|
|
|
**Normal Mode:**
|
|
|
|
- `j/k` - Scroll down/up
|
|
- `gg/G` - Jump to top/bottom
|
|
- `Ctrl+d/u` - Half page scroll
|
|
- `/` - Search, `n/N` - Next/prev match
|
|
- `i` - Enter insert mode
|
|
- `:` - Command mode (`:q` quit, `:w` save)
|
|
|
|
**Configuration:**
|
|
|
|
```json
|
|
{
|
|
"vim": {
|
|
"enabled": true,
|
|
"startInNormalMode": true
|
|
}
|
|
}
|
|
```
|
|
|
|
### Command Menu
|
|
|
|
Press `/` to access all commands organized by category.
|
|
|
|
|
|
|
|
**Available Commands:**
|
|
|
|
| Category | Command | Description |
|
|
| -------- | ------------ | ----------------------------------------------- |
|
|
| General | `/help` | Show available commands |
|
|
| General | `/clear` | Clear conversation history |
|
|
| General | `/exit` | Exit the chat |
|
|
| Session | `/save` | Save current session |
|
|
| Session | `/context` | Show context information |
|
|
| Session | `/usage` | Show token usage with color-coded progress bars |
|
|
| Session | `/remember` | Save a learning about the project |
|
|
| Session | `/learnings` | Show saved learnings |
|
|
| Settings | `/model` | Select AI model |
|
|
| Settings | `/agent` | Select agent |
|
|
| Settings | `/mode` | Switch interaction mode |
|
|
| Settings | `/provider` | Switch LLM provider |
|
|
| Settings | `/status` | Show provider status |
|
|
| Settings | `/theme` | Change color theme |
|
|
| Settings | `/mcp` | Manage MCP servers |
|
|
| Account | `/whoami` | Show logged in account |
|
|
| Account | `/login` | Authenticate with provider |
|
|
| Account | `/logout` | Sign out from provider |
|
|
|
|
### Agent Mode with Diff View
|
|
|
|
When CodeTyper modifies files, you see a clear diff view of changes.
|
|
|
|
|
|
|
|
**Interaction Modes:**
|
|
|
|
- **Agent** - Full access, can modify files
|
|
- **Ask** - Read-only, answers questions
|
|
- **Code Review** - Review PRs and diffs
|
|
|
|
### Permission System
|
|
|
|
Granular control over what CodeTyper can do. Every file operation requires approval.
|
|
|
|
|
|
|
|
**Permission Scopes:**
|
|
|
|
- `[y]` Yes, this once
|
|
- `[s]` Yes, for this session
|
|
- `[a]` Always allow for this project
|
|
- `[g]` Always allow globally
|
|
- `[n]` No, deny this request
|
|
|
|
### Model Selection
|
|
|
|
Access to multiple AI models through GitHub Copilot.
|
|
|
|
|
|
|
|
**Available Models:**
|
|
|
|
- GPT-5, GPT-5-mini (Unlimited)
|
|
- GPT-5.2-codex, GPT-5.1-codex
|
|
- Grok-code-fast-1
|
|
- And more...
|
|
|
|
### Copilot Usage Display
|
|
|
|
Real-time monitoring of your GitHub Copilot quota usage directly in the Activity Panel.
|
|
|
|
**Features:**
|
|
|
|
- **Premium Requests** - Track your premium request quota
|
|
- **Chat** - Monitor chat message limits
|
|
- **Completions** - View code completion quota
|
|
- **Color-coded Progress Bars** - Green (>40%), Yellow (5-40%), Red (≤5%)
|
|
- **Auto-refresh** - Updates every 60 seconds and after each task
|
|
- **Reset Date** - Shows when quotas reset
|
|
|
|
Accessible via the Activity Panel (`Ctrl+O`) when using GitHub Copilot provider.
|
|
|
|
### Theme System
|
|
|
|
15+ built-in themes to customize your experience.
|
|
|
|
|
|
|
|
**Available Themes:**
|
|
default, dracula, nord, tokyo-night, gruvbox, monokai, catppuccin, one-dark, solarized-dark, github-dark, rose-pine, kanagawa, ayu-dark, cargdev-cyberpunk, pink-purple
|
|
|
|
## Providers
|
|
|
|
| Provider | Models | Auth Method | Use Case |
|
|
| ------------------ | --------------------------- | ------------------- | --------------------------- |
|
|
| **GitHub Copilot** | GPT-5, Claude, Gemini | OAuth (device flow) | Cloud-based, high quality |
|
|
| **Ollama** | Llama, DeepSeek, Qwen, etc. | Local server | Private, offline, zero-cost |
|
|
|
|
### Cascade Mode
|
|
|
|
When both providers are available, CodeTyper can use them together:
|
|
|
|
1. **Ollama** processes the request first (fast, local)
|
|
2. **Copilot** audits the response for issues
|
|
3. Quality scores update based on audit results
|
|
4. Future requests route based on learned performance
|
|
|
|
Check provider status with `/status`:
|
|
|
|
```
|
|
═══ Provider Status ═══
|
|
|
|
Current Provider: copilot
|
|
Cascade Mode: Enabled
|
|
|
|
Ollama:
|
|
Status: ● Available
|
|
Quality Score: 72%
|
|
|
|
Copilot:
|
|
Status: ● Available
|
|
```
|
|
|
|
## Configuration
|
|
|
|
Settings are stored in `~/.config/codetyper/config.json`:
|
|
|
|
```json
|
|
{
|
|
"provider": "copilot",
|
|
"model": "auto",
|
|
"theme": "default",
|
|
"cascadeEnabled": true,
|
|
"maxIterations": 20,
|
|
"timeout": 30000
|
|
}
|
|
```
|
|
|
|
### Project Context
|
|
|
|
CodeTyper reads project-specific context from:
|
|
|
|
- `.github/` - GitHub workflows and templates
|
|
- `.codetyper/` - Project-specific rules and learnings
|
|
- `rules.md` - Custom instructions for the AI
|
|
|
|
## CLI Usage
|
|
|
|
```bash
|
|
# Start interactive TUI
|
|
codetyper
|
|
|
|
# Start with a prompt
|
|
codetyper "Create a REST API with Express"
|
|
|
|
# Continue last session
|
|
codetyper --continue
|
|
|
|
# Resume specific session
|
|
codetyper --resume <session-id>
|
|
|
|
# Use specific provider
|
|
codetyper --provider ollama
|
|
|
|
# Print mode (non-interactive)
|
|
codetyper --print "Explain this codebase"
|
|
```
|
|
|
|
## Tools
|
|
|
|
CodeTyper has access to these built-in tools:
|
|
|
|
| Tool | Description |
|
|
| ------------ | ----------------------------------- |
|
|
| `bash` | Execute shell commands |
|
|
| `read` | Read file contents |
|
|
| `write` | Create or overwrite files |
|
|
| `edit` | Find and replace in files |
|
|
| `glob` | Find files by pattern |
|
|
| `grep` | Search file contents |
|
|
| `lsp` | Language Server Protocol operations |
|
|
| `web_search` | Search the web |
|
|
| `todo-read` | Read current todo list |
|
|
| `todo-write` | Update todo list |
|
|
|
|
### MCP Integration
|
|
|
|
Connect external MCP (Model Context Protocol) servers for extended capabilities:
|
|
|
|
```bash
|
|
# Browse and search available servers
|
|
/mcp browse # Interactive browser
|
|
/mcp search <query> # Search by keyword
|
|
/mcp popular # Show popular servers
|
|
/mcp categories # List all categories
|
|
|
|
# Install a server
|
|
/mcp install sqlite
|
|
/mcp install github
|
|
|
|
# Manage servers
|
|
/mcp status # Show connected servers
|
|
/mcp connect # Connect all servers
|
|
/mcp disconnect # Disconnect all servers
|
|
/mcp tools # List available tools
|
|
/mcp add # Add custom server
|
|
```
|
|
|
|
**MCP Browser Features:**
|
|
|
|
- Search by name, description, or tags
|
|
- Filter by category (database, web, AI, etc.)
|
|
- View server details and required environment variables
|
|
- One-click installation and connection
|
|
- 15+ verified servers from Anthropic
|
|
|
|
## Extensibility
|
|
|
|
### Hooks System
|
|
|
|
Lifecycle hooks for intercepting tool execution and session events.
|
|
|
|
**Hook Events:**
|
|
|
|
- `PreToolUse` - Validate/modify before tool execution
|
|
- `PostToolUse` - Side effects after tool execution
|
|
- `SessionStart` - At session initialization
|
|
- `SessionEnd` - At session termination
|
|
- `UserPromptSubmit` - When user submits input
|
|
- `Stop` - When execution stops
|
|
|
|
**Configuration** (`.codetyper/hooks.json`):
|
|
|
|
```json
|
|
{
|
|
"hooks": [
|
|
{
|
|
"event": "PreToolUse",
|
|
"script": ".codetyper/hooks/validate.sh",
|
|
"timeout": 5000
|
|
},
|
|
{ "event": "PostToolUse", "script": ".codetyper/hooks/notify.sh" }
|
|
]
|
|
}
|
|
```
|
|
|
|
**Exit Codes:**
|
|
|
|
- `0` - Allow (optionally output `{"updatedInput": {...}}` to modify args)
|
|
- `1` - Warn but continue
|
|
- `2` - Block execution
|
|
|
|
### Plugin System
|
|
|
|
Extend CodeTyper with custom tools, commands, and hooks.
|
|
|
|
**Plugin Structure:**
|
|
|
|
```
|
|
.codetyper/plugins/{name}/
|
|
├── plugin.json # Manifest
|
|
├── tools/
|
|
│ └── *.ts # Custom tool definitions
|
|
├── commands/
|
|
│ └── *.md # Slash commands
|
|
└── hooks/
|
|
└── *.sh # Plugin-specific hooks
|
|
```
|
|
|
|
**Manifest** (`plugin.json`):
|
|
|
|
```json
|
|
{
|
|
"name": "my-plugin",
|
|
"version": "1.0.0",
|
|
"tools": [{ "name": "custom_tool", "file": "tool.ts" }],
|
|
"commands": [{ "name": "mycommand", "file": "cmd.md" }]
|
|
}
|
|
```
|
|
|
|
**Custom Tool Definition:**
|
|
|
|
```typescript
|
|
import { z } from "zod";
|
|
export default {
|
|
name: "custom_tool",
|
|
description: "Does something",
|
|
parameters: z.object({ input: z.string() }),
|
|
execute: async (args, ctx) => ({
|
|
success: true,
|
|
title: "Done",
|
|
output: "...",
|
|
}),
|
|
};
|
|
```
|
|
|
|
### Session Forking
|
|
|
|
Branch and rewind session history for experimentation.
|
|
|
|
**Commands:**
|
|
| Command | Description |
|
|
|---------|-------------|
|
|
| `/snapshot [name]` | Create checkpoint |
|
|
| `/rewind [n\|name]` | Go back to snapshot |
|
|
| `/fork [name]` | Branch current session |
|
|
| `/forks` | List all forks |
|
|
| `/switch [name]` | Switch to fork |
|
|
|
|
Sessions are stored in `.codetyper/sessions/` with automatic commit message suggestions.
|
|
|
|
## Roadmap
|
|
|
|
### v0.4.0 - Agent Completion
|
|
|
|
The next major release focuses on production-ready autonomous agent execution:
|
|
|
|
| Feature | Issue | Status |
|
|
| --------------------------------------- | ----------------------------------------------------------- | ------- |
|
|
| Plan Approval Gate | [#111](https://github.com/CarGDev/codetyper.cli/issues/111) | Planned |
|
|
| Diff Preview Before Write | [#112](https://github.com/CarGDev/codetyper.cli/issues/112) | Planned |
|
|
| Execution Control (Pause/Resume/Abort) | [#113](https://github.com/CarGDev/codetyper.cli/issues/113) | Planned |
|
|
| Consistent Model Behavior | [#114](https://github.com/CarGDev/codetyper.cli/issues/114) | Planned |
|
|
| Quality Gates (TypeScript, Lint, Tests) | [#115](https://github.com/CarGDev/codetyper.cli/issues/115) | Planned |
|
|
|
|
### Known Issues
|
|
|
|
- Agent mode executes without waiting for user plan approval
|
|
- Different LLM models may behave inconsistently during agent execution
|
|
- No diff preview before file modifications
|
|
|
|
See [CHANGELOG](docs/CHANGELOG.md) for full version history.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Watch mode
|
|
bun run dev
|
|
|
|
# Type check
|
|
bun run typecheck
|
|
|
|
# Build
|
|
bun run build
|
|
|
|
# Run tests
|
|
bun test
|
|
|
|
# Lint
|
|
bun run lint
|
|
```
|
|
|
|
## Recent Changes (v0.4.2)
|
|
|
|
- **Session Stats on Exit**: Displays detailed session summary when quitting:
|
|
- Total API time spent, session duration, code changes (+/-)
|
|
- Per-model token usage breakdown with resume command
|
|
- **Pink Purple Theme**: New built-in color theme
|
|
- **Activity Panel Toggle**: `Ctrl+O` to show/hide the activity panel
|
|
- **Image Paste Fix**: Fixed race condition where pasted images were silently dropped
|
|
- **Terminal Exit Fix**: Fixed `997;1n` garbage text appearing on exit
|
|
- **@ and / Anywhere**: File picker and command menu now work at any cursor position
|
|
- **Plan Approval Gate**: User confirmation before agent executes plans
|
|
- **Execution Control**: Pause, resume, and abort agent execution
|
|
- **Text Clipboard Copy/Read**: Cross-platform clipboard operations with mouse selection
|
|
|
|
See [CHANGELOG](docs/CHANGELOG.md) for complete version history.
|
|
|
|
## Documentation
|
|
|
|
- [Changelog](docs/CHANGELOG.md) - Version history and changes
|
|
- [Contributing](docs/CONTRIBUTING.md) - How to contribute
|
|
|
|
## License
|
|
|
|
MIT - See [LICENSE](LICENSE) for details.
|