Skip to content
BranchesTags

Repository files navigation

Localcoder

Localcoder REPL screenshot

Chinese version: README.zh.md

📖 Overview

Localcoder is a local-first command-line coding assistant implemented in Rust. It already includes:

  • ✅ Streaming chat and one-shot execution for Ollama, OpenAI-compatible APIs, and LM Studio
  • ✅ Tool calling runtime with file, search, Bash, web, and LSP tools
  • ✅ Interactive REPL with oxink input, model switching, session resume, config UI, and output styles
  • ✅ Local server mode with HTTP and WebSocket entrypoints
  • ✅ Context compaction, git workflows, memory extraction, plan mode, and skills
  • ✅ Lightweight runtime with fast startup and low memory usage

Compared with the JavaScript version, the Rust version starts about 10x faster and uses about 10x less memory.

📊 Implementation Status

The staged roadmap in docs/P00-plan.md is mostly implemented. Current status: 17 / 22 stages completed.

Stage Area Status Deliverable
S00 Basic chat loop ✅ REPL, streaming API, one-shot mode
S01 Tool system architecture ✅ Tool trait, registry, tool dispatch loop
S02 File tools ✅ Read / Edit / Write
S03 Search tools ✅ Glob / Grep
S04 Command execution ✅ Bash tool with safety checks
S05 Session persistence ✅ JSONL session storage, --continue, --resume, /resume
S06 Config system ✅ settings.json, /config, persisted UI preferences
S07 Permission system ❌ Rule engine and user confirmation are not implemented yet
S08 Context compaction ✅ Automatic compaction, token estimation, /compact
S09 Git integration ✅ /diff, /review, /commit
S10 Memory system ✅ Four memory types and automatic extraction
S11 Sub-agents ❌ Forked sub-agents and worktree isolation are not implemented yet
S12 Plan mode ✅ EnterPlanMode, ExitPlanMode, TodoWrite, /plan
S13 Skill system ✅ SKILL.md, skill_tool, /skills, /<skill-name>
S14 Web tools ✅ WebSearch, WebFetch, /web, /fetch
S15 Cost tracking ❌ Token accounting and /cost are not implemented yet
S16 Multi-provider support ❌ Bedrock / Vertex / Foundry are not implemented yet
S17 MCP integration ❌ MCP client and transport support are not implemented yet
S18 Output styles ✅ Output style loading and /output-style
S19 LSP integration ✅ Language-server-backed code navigation via Lsp
S20 Server mode ✅ Axum-based local HTTP and WebSocket server via /server
S21 REPL slash menu ✅ Slash command suggestions and picker for built-in and skill commands

🚀 Quick Start

1. Install the Binary

Option 1: Use the install script

curl -fsSL https://raw.githubusercontent.com/iamwjun/localcoder/main/install.sh | bash

Supported platforms:

  • macOS (arm64 / x86_64)
  • Linux (x86_64 / aarch64)

Option 2: Build from source

git clone https://github.com/iamwjun/localcoder.git
cd localcoder
cargo build --release

2. Configure a Provider

On first launch, Localcoder ensures that $HOME/.localcoder/settings.json exists.

LLM settings are loaded from that home-level file. Example configurations:

Ollama

{
  "llm": {
    "type": "ollama",
    "base_url": "http://localhost:11434",
    "model": "qwen3.5:4b"
  }
}

LM Studio

{
  "llm": {
    "type": "lmstudio",
    "base_url": "http://localhost:1234",
    "model": "qwen/qwen3-coder-30b"
  }
}

OpenAI-compatible

{
  "llm": {
    "type": "openai",
    "base_url": "https://api.openai.com/v1",
    "api_key": "sk-...",
    "model": "gpt-4o-mini"
  }
}

Optional project-local overrides can live in .localcoder/settings.json. Today that path is especially useful for UI and LSP settings:

{
  "ui": {
    "theme": "default",
    "tips": true,
    "output_style": "default"
  },
  "lsp": {
    "enabled": true,
    "servers": [
      {
        "name": "rust-analyzer",
        "command": "rust-analyzer",
        "extensions": [".rs"],
        "language_id": "rust"
      }
    ]
  }
}

If you use Ollama, make sure the local service is running and that at least one model has been pulled:

ollama serve
ollama pull qwen3.5:4b

3. First Run

# Start the interactive REPL
localcoder

On startup the REPL shows a compact banner with session status, UI state, and active endpoint. When tips are enabled it also prints one random startup tip, and the active llm / model is rendered below the input box.

You can edit $HOME/.localcoder/settings.json manually, or switch models from the REPL with /model.

4. Run

# Interactive REPL mode
localcoder

# One-shot query
localcoder -- "Hello, introduce yourself"

# Continue the latest session for this project
localcoder --continue

# Resume a specific session
localcoder --resume s1712345678-12345

# Start the local server in the foreground
localcoder -- "/server"

# Start the local server on a custom address
localcoder -- "/server 127.0.0.1:4000"

Useful interaction details:

  • Ctrl-C, Ctrl-D, /exit, and /quit all leave the main REPL
  • /resume opens a session picker and re-renders the loaded conversation history
  • /config manages theme and startup tip visibility
  • /output-style switches the active response style without editing JSON by hand

🌐 Server Mode

Localcoder can also run as a local HTTP and WebSocket server. The default bind address is 127.0.0.1:3000.

You can start it in either mode:

# Start in the REPL, but keep the REPL usable
/server
/server status
/server stop

# Start in one-shot mode and keep the process in the foreground
localcoder -- "/server"
localcoder -- "/server 127.0.0.1:4000"

Available routes:

  • GET /healthz
  • POST /v1/message
  • GET /v1/ws

Example HTTP request:

curl -X POST http://127.0.0.1:3000/v1/message \
  -H "content-type: application/json" \
  -d '{
    "message": "Explain the role of src/main.rs",
    "session_id": "",
    "output_style": "default"
  }'

Example response:

{
  "session_id": "s1746690000000-12345-0",
  "reply": "src/main.rs bootstraps configuration, registers tools, and decides between REPL and one-shot execution.",
  "model": "qwen3.5:4b"
}

WebSocket messages are JSON-based and currently one request maps to one full agent execution:

{
  "type": "message",
  "message": "Continue the previous turn and summarize main.rs",
  "session_id": "s1746690000000-12345-0"
}

The server is intentionally local-first:

  • It listens on 127.0.0.1 by default
  • There is no built-in auth or TLS yet
  • wss should be handled by a reverse proxy if needed

🛠️ Built-in Tools

The current toolset includes:

  • File tools: Read, Edit, Write
  • Search tools: Glob, Grep
  • Shell execution: Bash
  • Web access: WebSearch, WebFetch
  • Code intelligence: Lsp

Example prompts:

localcoder -- "Read the first 5 lines of src/main.rs"
localcoder -- "Write 'hello world' into /tmp/test.txt"
localcoder -- "search process_chunk function"
localcoder -- "Run rg \"SessionStore\" in the project root"
localcoder -- "Fetch https://www.rust-lang.org/"

📝 REPL Commands

Command Description
/resume List and resume a previous session
/compact Manually compact long conversation context
/diff Show the current git diff
/review Review the current git diff with the model
/commit [title] Generate a commit message and create a git commit
/memory List saved memories
/output-style [name] List or switch output styles
/web <query> Search the public web directly
/fetch <url> Fetch a public web page
/server [status|stop|host:port] Start, stop, or inspect the local HTTP/WebSocket server
/plan Show plan-mode status
/plan on Enable plan mode manually
/plan off Disable plan mode manually
/plan clear Clear the persisted todo list
/skills List available user-invocable skills
/<skill-name> [args] Invoke a user skill directly
/config Configure UI settings such as theme and tips
/help Show the available commands
/clear Clear conversation history
/history Show conversation history in JSON format
/model Fetch models from the active provider endpoint, switch the active model, and update $HOME/.localcoder/settings.json
/count Show the message count
/version Show the current version
/quit Exit the REPL
/exit Exit the REPL

📦 Project Structure

localcoder/
├── install.sh           # Install script with platform detection
├── Cargo.toml           # Rust project manifest
├── CHANGELOG.md         # Release notes
├── README.md            # English documentation
├── README.zh.md         # Chinese documentation
├── docs/                # Roadmap and stage-by-stage implementation notes
│   ├── P00-plan.md      # Overall staged plan
│   └── S00-S21*.md      # Detailed stage documents
├── examples/            # Example programs
│   ├── basic.rs          # Basic API usage
│   ├── streaming.rs      # Streaming responses
│   ├── conversation.rs   # Multi-turn conversation
│   ├── custom_model.rs   # Custom model parameters
│   └── error_handling.rs # Error handling
└── src/                 # Source code
    ├── main.rs           # Program entry point
    ├── api.rs            # Provider clients and streaming requests
    ├── compact.rs        # Context compaction
    ├── config.rs         # REPL/UI config loading and persistence
    ├── engine.rs         # Agent loop and tool dispatch
    ├── git.rs            # Git workflow helpers
    ├── memory.rs         # Memory extraction and storage
    ├── output_style.rs   # Output style loading and prompt injection
    ├── plan.rs           # Plan mode state and todo management
    ├── repl.rs           # Interactive REPL interface
    ├── runtime.rs        # Shared runtime/bootstrap helpers
    ├── server.rs         # Local HTTP and WebSocket server mode
    ├── session.rs        # JSONL session persistence
    ├── skills.rs         # SKILL.md loading and activation
    ├── tools/            # Built-in tools
    ├── services/lsp/     # Language server integration
    └── types.rs          # Shared types

📋 Tech Stack

Component Selection
Async runtime tokio 1.40
HTTP client reqwest 0.12
Local server axum 0.8
JSON handling serde + serde_json 1.0
Prompt/input UI oxink 0.1.5
Error handling anyhow
Language tooling built-in LSP manager + external language servers

📈 Performance

Metric JavaScript Rust Improvement
Startup time ~100ms ~10ms 10x
Memory usage ~50MB ~5MB 10x
Binary size N/A 5-8MB Standalone deployment

📚 What You Can Learn

This project is useful for learning:

  1. Async Rust: tokio, async/await, and stream handling
  2. HTTP clients: reqwest and JSON-based APIs
  3. Systems programming: error handling, ownership, and type safety
  4. CLI development: terminal UX, prompt rendering, and command-line workflows
  5. Provider integration: Ollama, OpenAI-compatible APIs, and LM Studio model management

🤖 Possible Extensions

You can continue extending this project with:

  • Permission management and sandboxing
  • Sub-agent collaboration
  • Token cost tracking
  • Multi-provider backends such as Bedrock / Vertex / Foundry
  • MCP integration
  • GUI frontends with egui or iced
  • WebAssembly support for running in the browser

📄 License

MIT License

About

local rust claude code

Resources

Readme
MIT license
Activity

Stars

36 stars

Watchers

3 watching

Forks

6 forks
Report repository

Releases

Packages

Contributors

Languages