llama-code

A CLI coding assistant powered by local Llama models via Ollama. Think Claude Code, but running entirely on your machine.

Features

• Agentic tool calling — reads, writes, edits files and runs commands autonomously
• Multi-turn reasoning — chains tool calls to complete complex tasks
• Interactive REPL with streaming responses (Ink-based terminal UI)
• One-shot mode for scripting and piped workflows
• MCP support — extend with Model Context Protocol servers
• Hooks system — PreToolUse, PostToolUse, UserPromptSubmit, Stop events
• Session persistence — save/resume conversations
• Skills & Memory — load markdown skill guides, persistent memory across sessions
• Permission model — ask mode (confirm writes) or auto mode (approve all)
• Robust JSON recovery — 5-stage pipeline to handle Llama's unreliable tool call JSON
• Special token filtering — strips <|python_tag|> and other Llama artifacts from output

Prerequisites

• Node.js >= 18.0.0
• Ollama — Install from ollama.com
• A pulled model:

  ollama pull llama3.1:8b

Installation

git clone https://github.com/trevi00/llama-code.git
cd llama-code
npm install
npm run build

To use globally:

npm link

Usage

Interactive REPL

llama-code

One-shot mode

llama-code "list all TypeScript files in src/"

Piped input

echo "explain this code" | llama-code

Options

-m, --model <model>     Ollama model (default: llama3.1:8b)
--base-url <url>        Ollama server URL (default: http://localhost:11434)
--auto                  Auto-approve all tool executions
--max-turns <n>         Maximum agentic turns (default: 30)
--num-ctx <n>           Context window size (auto-detected if omitted)
--debug                 Enable debug logging
--resume <id>           Resume a previous session

REPL Commands

Command	Description
/help	Show available commands
/clear	Clear conversation
/model [name]	Show or switch model
/sessions	List saved sessions
/resume [id]	Resume a session
/diff	Show git diff
/status	Show git status
/log [n]	Show recent commits
/memory list	List saved memories
/doctor	Run diagnostics
/compact	Compress conversation context
/exit	Exit REPL

Built-in Tools

Tool	Description
Bash	Execute shell commands
Read	Read file contents with line numbers
Write	Create or overwrite files
Edit	Replace exact text in files (with diff output)
Glob	Find files by name pattern
Grep	Search file contents with regex
Agent	Launch sub-agents for parallel research

Configuration

Create .llama-code.json in your home directory (user-level) or project root (project-level):

{
  "model": "qwen2.5-coder:7b",
  "temperature": 0.7,
  "maxTurns": 50,
  "permissionMode": "ask",
  "keepAlive": "5m",
  "systemPromptExtra": "Always respond in Korean.",
  "allowedTools": ["Read", "Glob", "Grep"],
  "deniedTools": ["Bash"]
}

Priority order: defaults < ~/.llama-code.json < ./.llama-code.json < env vars < CLI flags

Environment Variables

Variable	Description
LLAMA_CODE_MODEL	Override model name
LLAMA_CODE_BASE_URL	Override Ollama URL
LLAMA_CODE_NUM_CTX	Override context window size

Project Instructions

Place a LLAMA.md or CLAUDE.md file in your project root. Its contents will be injected into the system prompt as project-specific instructions.

MCP Servers

Add MCP servers to .llama-code.json:

{
  "mcpServers": {
    "my-server": {
      "type": "stdio",
      "command": "node",
      "args": ["path/to/server.js"]
    }
  }
}

Hooks

Add hooks to .llama-code.json:

{
  "hooks": {
    "PreToolUse": [
      { "command": "bash -c 'echo hook fired'", "timeout": 5000 }
    ]
  }
}

Supported events: UserPromptSubmit, PreToolUse, PostToolUse, Stop

Architecture

src/
├── services/ollama/     # Ollama API adapter, streaming, JSON recovery
├── query/               # Agentic loop, tool execution, context management
├── tools/               # Built-in tools (Bash, Read, Write, Edit, Glob, Grep, Agent)
├── ui/                  # Ink-based terminal UI (REPL)
├── cli/                 # One-shot mode
├── mcp/                 # MCP client integration
├── hooks/               # Hook system
├── session/             # Session persistence (JSONL)
├── skills/              # Skill file loader and matcher
├── memory/              # Persistent memory store
├── config/              # Layered settings
├── prompts/             # System prompt builder
├── context/             # Project context loader
└── types/               # Shared type definitions

Development

npm run dev          # Run with tsx (no build needed)
npm run build        # TypeScript compile
npm test             # Run tests
npm run test:watch   # Watch mode
npm run test:coverage # Coverage report

Recommended Models

Model	Size	Best for
llama3.1:8b	4.7GB	Default, balanced
qwen2.5-coder:7b	4.7GB	Code-focused tasks
qwen2.5:7b	4.7GB	Better multilingual
exaone3.5:7.8b	4.8GB	Korean language
gemma3:12b	8.1GB	Higher quality (needs more VRAM)

License

MIT