⚡ LocalCode

An AI coding agent that runs entirely in your terminal — no cloud account required.
Point it at a local model (Ollama, LM Studio) and start building.

---

What it does

LocalCode is an autonomous AI coding agent with a keyboard-driven terminal UI. Describe a task — the agent reads your codebase, edits files, runs commands, and commits to git. Every write operation shows a diff preview and asks for confirmation before applying.

---

Requirements

• Node.js 18+ — nodejs.org
• A running local LLM server — Ollama or LM Studio

---

Install

npm install -g localcode-agent

Then run it inside any project:

localcode

---

Quick start

1. Start a local model server

Ollama (recommended — free, Linux / macOS / Windows)

# Install from https://ollama.com, then:
ollama serve
ollama pull deepseek-coder

LM Studio — download from lmstudio.ai, load a model, click Start Local Server.

---

2. Connect

On first launch, type /connect to open the connection popup, pick your provider, and enter the address. The config is saved to ~/.localcode/config.json.

---

3. Give it a task

localcode fix the auth bug in src/auth.ts
localcode add unit tests for the user service
localcode explain the architecture of this project

Or just open the TUI and type naturally.

---

Keyboard shortcuts

Key	Action
Enter	Send message / run task
Tab	Autocomplete or toggle BUILD ↔ PLAN mode
↑ / ↓	Browse input history (or scroll chat when input is empty)
PageUp / PageDown	Scroll chat history
Ctrl+C	Abort running agent / quit
Ctrl+L	Clear chat
Ctrl+K	Clear input line
Esc	Close popup / cancel

Shell passthrough — prefix a command with $ or ! to run it directly:

$ npm test
! git log --oneline -10

Inject a message while the agent is running — just type and press Enter. Short messages are sent to the agent immediately; longer ones are queued and run after the current task finishes.

---

Slash commands

Type / to open the searchable command picker.

Command	What it does
/connect	Open the server connection popup
/model	Pick a model (searchable popup)
/models	List all available models
/doctor	Check server connectivity and config
/trust <path>	Trust a folder — auto-approve all write ops inside it
/trust	List all trusted paths
/trust remove <path>	Remove trust from a folder
/config	Show current configuration
/config provider ollama	Switch to Ollama
/config provider lmstudio	Switch to LM Studio
/config model <name>	Set the active model
/config url <url>	Override the server base URL
/config temperature <0–1>	Adjust model temperature
/attach	Attach a file or image to your message
/compact	Summarize and compress the conversation history
/session save <name>	Save the current session
/session load <name>	Restore a saved session
/lsp	Run diagnostics — tsc, eslint, cargo check, go vet, ruff/pyflakes, rubocop, dotnet build
/lsp hover <file>:<line>:<col>	Hover info for a symbol via the LSP server (e.g. type, signature, docs)
/lsp def <file>:<line>:<col>	Jump to definition — returns the file and line where a symbol is defined
/plugin	List installed plugins
/plugin install <path>	Install a plugin
/clear	Clear the chat
/exit	Quit

---

Confirmation & trust

Every file write and shell command asks for confirmation before running:

Allow  Write file: src/auth.ts
[y] yes  /  [n] no  /  [t] trust folder

• y — approve once
• t — trust the folder permanently (all future ops in this path and subfolders are auto-approved, including new files)
• n — deny

Dangerous operations (rm -rf, sudo, force-push, etc.) always require explicit confirmation even in trusted folders.

Manage trusted paths:

/trust .                  # trust current directory
/trust /home/user/project # trust absolute path
/trust                    # list all trusted paths
/trust remove <path>      # remove trust

---

BUILD vs PLAN mode

Press Tab (with empty input) to toggle between modes:

• BUILD — agent uses tools, edits files, runs commands
• PLAN — agent thinks through the task and returns a structured plan without touching anything

---

File reading

The agent reads entire files. For large files it shows the total line count and supports ranged reads:

{"tool": "read_file", "arguments": {"path": "src/big.ts", "start_line": 100, "end_line": 200}}

---

Conversation history & context

The last 20 turns (40 messages) are kept in context and sent to the model each iteration. Use /compact to summarize and free up context when working on long tasks.

---

Discord Rich Presence

LocalCode shows your current status in Discord ("Idle", "Thinking…", "Running agent") with the active folder name and elapsed time.

It connects automatically to Discord if it is running. No setup needed for users — just install and go.

---

Configuration file

~/.localcode/config.json is created automatically. Direct editing is supported:

{
  "llm": {
    "provider": "ollama",
    "model": "deepseek-coder:latest",
    "baseURL": "http://localhost:11434",
    "temperature": 0.1
  },
  "trustedPaths": [
    "/home/user/projects/myapp"
  ]
}

---

What the agent can do

• Read, write, edit, move, copy, delete files
• Search inside files (grep) and find files by pattern
• Run any shell command (PowerShell on Windows, bash on Linux/macOS)
• Create git commits
• Fetch URLs and make HTTP requests
• Run LSP diagnostics (tsc, cargo check, go vet, ruff/pyflakes, eslint, rubocop, dotnet build, and more)
• Get hover info and jump-to-definition via real LSP servers (typescript-language-server, rust-analyzer, gopls, pylsp, clangd)
• Retry automatically on errors and try alternative approaches when a tool fails

---

Error recovery

If the LLM stream fails, the agent retries up to 3 times automatically. If a tool returns an error, the model is told to try a different approach and continue rather than stopping.

---

Plugins

LocalCode supports plugins — Node.js modules that add custom slash commands and tools.

/plugin install ./my-plugin.js
/plugin list
/plugin remove my-plugin

---

Troubleshooting

"Ollama is not reachable"
Run ollama serve and check the URL with /doctor.

"LM Studio is not reachable"
Load a model in LM Studio and click Start Local Server (default port 1234).

"Model not found"
Use /models to list loaded models, /model to switch.

TUI looks broken / garbled
Requires a UTF-8 terminal with 256-color support.
Use Windows Terminal on Windows, or any modern terminal on macOS / Linux (iTerm2, Ghostty, Alacritty, kitty, etc.).

---

Language Intelligence (LSP)

LocalCode integrates with real Language Server Protocol servers to give the agent (and you) IDE-quality language intelligence — the same engine powering VS Code, Neovim, and others.

What it does

Feature	Description
Diagnostics (/lsp)	Runs errors and warnings via CLI tools (tsc, eslint, cargo check, …)
Hover (/lsp hover)	Gets the type, signature, or docs for any symbol
Go-to-definition (/lsp def)	Finds where any symbol is defined

The agent also has access to lsp_hover and lsp_definition as tools — it can look up types and definitions on its own while working.

Supported LSP servers

Language	Server	Install
TypeScript / JavaScript	typescript-language-server	npm install -g typescript-language-server typescript
Rust	rust-analyzer	rust-analyzer.github.io
Go	gopls	go install golang.org/x/tools/gopls@latest
Python	pylsp	pip install python-lsp-server
C / C++	clangd	clangd.llvm.org

Servers are optional — if none is installed for a language, /lsp still works via CLI tools. Hover and definition require the LSP server to be installed and on your PATH.

Usage

# Run diagnostics (CLI-based, always works):
/lsp
/lsp src/auth.ts

# Hover — get type info for the symbol at line 42, col 15:
/lsp hover src/auth.ts:42:15

# Go-to-definition — find where a symbol is defined:
/lsp def src/auth.ts:42:15

LSP servers start automatically on the first request and stay running in the background for fast subsequent calls.

---

Contributing

1. Fork and create a branch
2. npm install
3. npm run dev — watch mode
4. Edit files in src/
5. Test with node dist/localcode.js
6. Open a focused pull request (one feature or fix per PR)

---

License

MIT — free to use, modify, and distribute.