# Codetyper.nvim - LLM Documentation

> This file helps LLMs understand the Codetyper.nvim plugin structure and functionality.

## Overview

Codetyper.nvim is a Neovim plugin written in Lua that acts as an AI-powered coding partner. It integrates with multiple LLM APIs (Claude, OpenAI, Gemini, Copilot, Ollama) to help developers write code faster using a unique prompt-based workflow.

## Core Concept

Instead of having an AI generate entire files, Codetyper lets developers maintain control:

1. Developer opens a source file (e.g., `index.ts`)
2. A companion "coder file" is created (`index.coder.ts`)
3. Developer writes prompts using special tags: `/@ prompt @/`
4. When the closing tag is typed, the LLM generates code
5. Generated code is shown as a conflict for review
6. Developer accepts/rejects changes using keymaps

## Plugin Architecture

```
lua/codetyper/
├── init.lua              # Main entry, setup function
├── config.lua            # Configuration management
├── types.lua             # Lua type definitions
├── utils.lua             # Utility functions
├── commands.lua          # Vim command definitions
├── window.lua            # Split window management
├── parser.lua            # Parses /@ @/ tags
├── gitignore.lua         # Manages .gitignore entries
├── autocmds.lua          # Autocommands for tag detection
├── inject.lua            # Code injection strategies
├── health.lua            # Health check for :checkhealth
├── tree.lua              # Project tree logging
├── logs_panel.lua        # Standalone logs panel UI
├── cost.lua              # LLM cost tracking
├── credentials.lua       # Secure credential storage
├── llm/
│   ├── init.lua          # LLM interface, provider selection
│   ├── claude.lua        # Claude API client
│   ├── openai.lua        # OpenAI API client
│   ├── gemini.lua        # Google Gemini API client
│   ├── copilot.lua       # GitHub Copilot client
│   └── ollama.lua        # Ollama API client (local)
├── agent/
│   ├── init.lua          # Agent system entry point
│   ├── ui.lua            # Agent panel UI
│   ├── logs.lua          # Logging system
│   ├── tools.lua         # Tool definitions (read, edit, write, bash)
│   ├── executor.lua      # Tool execution logic
│   ├── parser.lua        # Parse tool calls from responses
│   ├── queue.lua         # Event queue with priority heap
│   ├── patch.lua         # Patch candidates with staleness detection
│   ├── confidence.lua    # Response confidence scoring
│   ├── worker.lua        # Async LLM worker
│   ├── scheduler.lua     # Event scheduler
│   ├── scope.lua         # Tree-sitter scope resolution
│   ├── intent.lua        # Intent detection from prompts
│   ├── conflict.lua      # Git-style conflict resolution
│   ├── linter.lua        # LSP diagnostics validation
│   └── search_replace.lua # SEARCH/REPLACE block parsing
├── ask/
│   ├── init.lua          # Ask panel entry point
│   └── ui.lua            # Ask panel UI (chat interface)
└── prompts/
    ├── init.lua          # System prompts for code generation
    └── agent.lua         # Agent-specific prompts
```

## .coder/ Folder

```
.coder/
├── tree.log           # Project structure, auto-updated
├── cost_history.json  # LLM cost tracking history
├── brain/             # Knowledge graph storage
│   ├── nodes/
│   ├── indices/
│   └── deltas/
├── agents/            # Custom agent definitions
└── rules/             # Project-specific rules
```

## Key Features

### 1. Multiple LLM Providers

```lua
llm = {
  provider = "claude", -- "claude", "openai", "gemini", "copilot", "ollama"
  claude = { api_key = nil, model = "claude-sonnet-4-20250514" },
  openai = { api_key = nil, model = "gpt-4o", endpoint = nil },
  gemini = { api_key = nil, model = "gemini-2.0-flash" },
  copilot = { model = "gpt-4o" },
  ollama = { host = "http://localhost:11434", model = "deepseek-coder:6.7b" },
}
```

### 2. Conflict Resolution System

Git-style diff visualization for code review:

```
<<<<<<< CURRENT
// Original code
=======
// AI-generated code
>>>>>>> INCOMING
```

**Keymaps (buffer-local when conflicts exist):**
| Key | Description |
|-----|-------------|
| `co` | Accept CURRENT (original) code |
| `ct` | Accept INCOMING (AI suggestion) |
| `cb` | Accept BOTH versions |
| `cn` | Delete conflict (accept NONE) |
| `cm` | Show conflict resolution menu |
| `]x` | Go to next conflict |
| `[x` | Go to previous conflict |
| `<CR>` | Show menu when on conflict |

**Menu keymaps:**
| Key | Description |
|-----|-------------|
| `1` | Accept current |
| `2` | Accept incoming |
| `3` | Accept both |
| `4` | Accept none |
| `q`/`<Esc>` | Close menu |

**Configuration:**
```lua
-- In conflict.lua
config = {
  lint_after_accept = true,      -- Check linter after accepting
  auto_fix_lint_errors = true,   -- Auto-queue fix
  auto_show_menu = true,         -- Show menu after injection
  auto_show_next_menu = true,    -- Show menu for next conflict
}
```

### 3. Linter Validation

Auto-check and fix lint errors after code injection:

```lua
-- In linter.lua
config = {
  auto_save = true,              -- Save file after injection
  diagnostic_delay_ms = 500,     -- Wait for LSP
  min_severity = vim.diagnostic.severity.WARN,
  auto_offer_fix = true,         -- Offer to fix errors
}
```

**Commands:**
- `:CoderLintCheck` - Check buffer for lint errors
- `:CoderLintFix` - Request AI to fix lint errors
- `:CoderLintQuickfix` - Show errors in quickfix
- `:CoderLintToggleAuto` - Toggle auto lint checking

### 4. SEARCH/REPLACE Block System

Reliable code editing with fuzzy matching:

```
<<<<<<< SEARCH
function oldCode() {
  // original
}
=======
function newCode() {
  // replacement
}
>>>>>>> REPLACE
```

**Configuration:**
```lua
-- In search_replace.lua
config = {
  fuzzy_threshold = 0.8,         -- Minimum similarity
  normalize_whitespace = true,   -- Ignore whitespace differences
  context_lines = 3,             -- Lines for context matching
}
```

### 5. Agent Mode

Autonomous coding assistant with tool access:

**Available Tools:**
- `read_file` - Read file contents
- `edit_file` - Edit files with find/replace
- `write_file` - Create or overwrite files
- `bash` - Execute shell commands

### 6. Event-Driven Scheduler

```
User types /@...@/ → Event queued → Scheduler dispatches → Worker processes → Patch created → Conflict shown
```

**Key concepts:**
- **PromptEvent**: Captures buffer state at prompt time
- **Optimistic Execution**: Ollama as fast scout
- **Confidence Scoring**: 5 heuristics
- **Staleness Detection**: Discard if buffer changed
- **Completion Safety**: Defer while autocomplete visible

### 7. Tree-sitter Scope Resolution

Prompts automatically resolve to enclosing scope:

```lua
function foo()
  /@ complete this function @/  -- Resolves to `foo`
end
```

**Scope types:** `function`, `method`, `class`, `block`, `file`

### 8. Intent Detection

| Intent | Keywords | Action |
|--------|----------|--------|
| complete | complete, finish, implement | replace |
| refactor | refactor, rewrite, simplify | replace |
| fix | fix, repair, debug, bug | replace |
| add | add, create, insert, new | insert |
| document | document, comment, jsdoc | replace |
| test | test, spec, unit test | append |
| optimize | optimize, performance | replace |
| explain | explain, what, how | none |

### 9. Cost Tracking

Track LLM API costs:
- Session costs tracked in real-time
- All-time costs in `.coder/cost_history.json`
- Pricing for 50+ models

### 10. Credentials Management

```vim
:CoderAddApiKey
```

Stored in `~/.local/share/nvim/codetyper/configuration.json`

**Priority:** stored credentials > config > environment variables

## Commands Reference

### Core Commands
| Command | Alias | Description |
|---------|-------|-------------|
| `:Coder open` | `:CoderOpen` | Open coder split |
| `:Coder close` | `:CoderClose` | Close coder split |
| `:Coder toggle` | `:CoderToggle` | Toggle coder split |
| `:Coder process` | `:CoderProcess` | Process last prompt |
| `:Coder status` | - | Show status |
| `:Coder focus` | - | Switch focus |
| `:Coder reset` | - | Reset processed prompts |

### Ask Panel
| Command | Alias | Description |
|---------|-------|-------------|
| `:Coder ask` | `:CoderAsk` | Open Ask panel |
| `:Coder ask-toggle` | `:CoderAskToggle` | Toggle Ask panel |
| `:Coder ask-clear` | `:CoderAskClear` | Clear chat |

### Agent Mode
| Command | Alias | Description |
|---------|-------|-------------|
| `:Coder agent` | `:CoderAgent` | Open Agent panel |
| `:Coder agent-toggle` | `:CoderAgentToggle` | Toggle Agent panel |
| `:Coder agent-stop` | `:CoderAgentStop` | Stop agent |

### Transform Commands
| Command | Alias | Description |
|---------|-------|-------------|
| `:Coder transform` | `:CoderTransform` | Transform all tags |
| `:Coder transform-cursor` | `:CoderTransformCursor` | Transform at cursor |
| - | `:CoderTransformVisual` | Transform selected |

### Conflict Resolution
| Command | Description |
|---------|-------------|
| `:CoderConflictToggle` | Toggle conflict mode |
| `:CoderConflictMenu` | Show resolution menu |
| `:CoderConflictNext` | Go to next conflict |
| `:CoderConflictPrev` | Go to previous conflict |
| `:CoderConflictStatus` | Show conflict status |
| `:CoderConflictResolveAll [keep]` | Resolve all |
| `:CoderConflictAcceptCurrent` | Accept original |
| `:CoderConflictAcceptIncoming` | Accept AI |
| `:CoderConflictAcceptBoth` | Accept both |
| `:CoderConflictAcceptNone` | Delete both |
| `:CoderConflictAutoMenu` | Toggle auto-show menu |

### Linter Validation
| Command | Description |
|---------|-------------|
| `:CoderLintCheck` | Check buffer |
| `:CoderLintFix` | AI fix errors |
| `:CoderLintQuickfix` | Show in quickfix |
| `:CoderLintToggleAuto` | Toggle auto lint |

### Queue & Scheduler
| Command | Alias | Description |
|---------|-------|-------------|
| `:Coder queue-status` | `:CoderQueueStatus` | Show status |
| `:Coder queue-process` | `:CoderQueueProcess` | Trigger processing |

### Processing Mode
| Command | Alias | Description |
|---------|-------|-------------|
| `:Coder auto-toggle` | `:CoderAutoToggle` | Toggle auto/manual |
| `:Coder auto-set <mode>` | `:CoderAutoSet` | Set mode |

### Brain & Memory
| Command | Description |
|---------|-------------|
| `:CoderMemories` | Show memories |
| `:CoderForget [pattern]` | Clear memories |
| `:CoderBrain [action]` | Brain management |
| `:CoderFeedback <type>` | Give feedback |

### Cost & Credentials
| Command | Description |
|---------|-------------|
| `:CoderCost` | Show cost window |
| `:CoderAddApiKey` | Add/update API key |
| `:CoderRemoveApiKey` | Remove credentials |
| `:CoderCredentials` | Show credentials |
| `:CoderSwitchProvider` | Switch provider |

### UI Commands
| Command | Description |
|---------|-------------|
| `:CoderLogs` | Toggle logs panel |
| `:CoderType` | Show mode switcher |

## Keymaps Reference

### Default Keymaps
| Key | Mode | Description |
|-----|------|-------------|
| `<leader>ctt` | Normal | Transform tag at cursor |
| `<leader>ctt` | Visual | Transform selected tags |
| `<leader>ctT` | Normal | Transform all tags |
| `<leader>ca` | Normal | Toggle Agent panel |
| `<leader>ci` | Normal | Open coder companion |

### Ask Panel Keymaps
| Key | Description |
|-----|-------------|
| `@` | Attach file |
| `Ctrl+Enter` | Submit |
| `Ctrl+n` | New chat |
| `Ctrl+f` | Add current file |
| `q` | Close |
| `Y` | Copy response |

### Agent Panel Keymaps
| Key | Description |
|-----|-------------|
| `<CR>` | Submit |
| `Ctrl+c` | Stop agent |
| `q` | Close |

### Logs Panel Keymaps
| Key | Description |
|-----|-------------|
| `q`/`<Esc>` | Close |

### Cost Window Keymaps
| Key | Description |
|-----|-------------|
| `q`/`<Esc>` | Close |
| `r` | Refresh |
| `c` | Clear session |
| `C` | Clear all |

## Configuration Schema

```lua
{
  llm = {
    provider = "claude",
    claude = { api_key = nil, model = "claude-sonnet-4-20250514" },
    openai = { api_key = nil, model = "gpt-4o", endpoint = nil },
    gemini = { api_key = nil, model = "gemini-2.0-flash" },
    copilot = { model = "gpt-4o" },
    ollama = { host = "http://localhost:11434", model = "deepseek-coder:6.7b" },
  },
  window = {
    width = 25,
    position = "left",
    border = "rounded",
  },
  patterns = {
    open_tag = "/@",
    close_tag = "@/",
    file_pattern = "*.coder.*",
  },
  auto_gitignore = true,
  auto_open_ask = true,
  auto_index = false,
  scheduler = {
    enabled = true,
    ollama_scout = true,
    escalation_threshold = 0.7,
    max_concurrent = 2,
    completion_delay_ms = 100,
    apply_delay_ms = 5000,
  },
}
```

## LLM Integration

### Claude API
- Endpoint: `https://api.anthropic.com/v1/messages`
- Auth: `x-api-key` header
- Supports tool use

### OpenAI API
- Endpoint: `https://api.openai.com/v1/chat/completions` (configurable)
- Auth: `Authorization: Bearer`
- Compatible with Azure, OpenRouter

### Gemini API
- Endpoint: `https://generativelanguage.googleapis.com/v1beta/models`
- Auth: API key in URL
- Supports function calling

### Copilot API
- Uses GitHub OAuth token from copilot.lua/copilot.vim
- OpenAI-compatible format

### Ollama API
- Endpoint: `{host}/api/generate` or `{host}/api/chat`
- No auth required locally

## Agent Tool Definitions

```lua
tools = {
  read_file = { path: string },
  edit_file = { path: string, find: string, replace: string },
  write_file = { path: string, content: string },
  bash = { command: string, timeout?: number },
}
```

## File Naming Convention

| Target File | Coder File |
|-------------|------------|
| `index.ts` | `index.coder.ts` |
| `utils.py` | `utils.coder.py` |
| `main.lua` | `main.coder.lua` |

Pattern: `name.coder.extension`

## Dependencies

- **Required**: Neovim >= 0.8.0, curl, plenary.nvim, nvim-treesitter
- **Optional**: telescope.nvim, copilot.lua/copilot.vim, nui.nvim

## Contact

- Author: cargdev
- Email: carlos.gutierrez@carg.dev
- Website: https://cargdev.io