80 lines
4.4 KiB
Markdown
80 lines
4.4 KiB
Markdown
# locode
|
|
|
|
An agentic coding CLI, in the spirit of Claude Code, for models running locally via [Ollama](https://ollama.com) or [LM Studio](https://lmstudio.ai). It talks to either backend's OpenAI-compatible `/v1/chat/completions` endpoint, so any model you can serve from either one works here.
|
|
|
|
## Install
|
|
|
|
```sh
|
|
npm install
|
|
npm run build
|
|
npm link # makes the `locode` command available globally
|
|
```
|
|
|
|
## Quick start
|
|
|
|
Make sure Ollama (`ollama serve`, default `http://localhost:11434`) or LM Studio (with a model loaded, default `http://localhost:1234`) is running, then:
|
|
|
|
```sh
|
|
locode --model qwen3-coder:30b
|
|
```
|
|
|
|
If you omit `--model`, locode lists the models available from the backend and lets you pick one with the arrow keys (Enter to confirm). Your saved default (via config or `$LOCODE_MODEL`) is pre-highlighted.
|
|
|
|
Pass `--model` explicitly to skip the picker entirely. Or persist your defaults so you don't need flags every time:
|
|
|
|
```sh
|
|
locode config set backend ollama
|
|
locode config set model qwen3-coder:30b
|
|
locode
|
|
```
|
|
|
|
List models available from the configured backend:
|
|
|
|
```sh
|
|
locode models
|
|
```
|
|
|
|
## How it works
|
|
|
|
locode is a full-screen terminal app built with [Ink](https://github.com/vadimdemedes/ink) (the same React-for-CLI framework Claude Code itself is built with) — it needs a real interactive terminal (piped/redirected input isn't supported). It takes over the terminal's alternate screen buffer (like `vim`/`htop`) — your prior scrollback is restored when you exit. The input box is always pinned to the last row of the window; the conversation fills the space above it and old messages scroll off the top as new ones arrive. Press Ctrl+C or type `/exit` to quit.
|
|
|
|
- **Backends**: `--backend ollama` (default) or `--backend lmstudio`, or `--base-url <url>` for anything else that speaks the same API.
|
|
- **Tools**: `read_file`, `list_files`, `grep` run automatically. `write_file`, `edit_file`, and `bash` show a diff/preview in a bordered box and ask you to pick Yes / Yes-always-this-session / No with the arrow keys before running.
|
|
- **Tool-calling mode**: on connect, locode probes whether the model reliably uses native OpenAI-style function calling. If not, it switches to a prompt-based fallback mode where the model is instructed to emit tool calls as fenced ` ```tool_call ``` ` JSON blocks, which locode parses itself. The result is cached per backend+model so future sessions skip the probe. Override with `--tool-mode native|fallback|auto` or the in-session `/mode` command.
|
|
|
|
Note: even models with genuine native tool-calling support occasionally emit a tool call as plain text instead of a real structured call — this is model sampling variance, not a bug. If a turn seems to "describe" a tool call instead of running it, just ask again or try `/mode fallback`.
|
|
|
|
## Slash commands
|
|
|
|
```
|
|
/model <name> switch the model used for the current backend
|
|
/backend <name> switch backend (ollama | lmstudio), keeps current model
|
|
/mode <name> view or force tool-call mode (native | fallback)
|
|
/status show current model, backend, tool-call mode, and cwd
|
|
/tools list available tools
|
|
/permissions list mutating tools allowed for the rest of this session
|
|
/clear clear conversation history
|
|
/help show this help
|
|
/exit, /quit exit
|
|
```
|
|
|
|
## Config
|
|
|
|
Config precedence: CLI flags > env vars (`LOCODE_BACKEND`, `LOCODE_MODEL`, `LOCODE_BASE_URL`) > persisted config file > defaults.
|
|
|
|
```sh
|
|
locode config set backend ollama
|
|
locode config set model qwen3-coder:30b
|
|
locode config get
|
|
locode config path
|
|
```
|
|
|
|
## Known limitations
|
|
|
|
- Requires a real interactive terminal (TTY) — you can't pipe input into it or run it from a non-interactive script.
|
|
- Native tool-calling reliability varies by model and is non-deterministic even for capable models (see above).
|
|
- No sandboxing beyond the confirmation prompts — mutating tools operate on the real filesystem/shell with the permissions of the user running `locode`. Only approve commands you understand.
|
|
- No session save/resume yet — each `locode` run starts a fresh conversation.
|
|
- No in-app scrollback — once a message scrolls off the top of the window it's gone until you resize the terminal taller (the conversation itself is still intact and sent to the model; this only affects what you can visually re-read).
|
|
- Windows shell quoting for the `bash` tool has only had light testing; behavior may differ from Unix shells for complex quoting.
|