Skip to content

Commit b0a49de

Browse files
ericmourantericmourant
authored
Merge pull request #14 from japer-technology/copilot/create-docs-local-chat
Add docs/local-chat.md documenting all Local Chat commands
2 parents d13b41c + f30bbad commit b0a49de

2 files changed

Lines changed: 131 additions & 0 deletions

File tree

‎.github-minimum-intelligence/docs/index.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ Six questions define the philosophical and architectural foundation of this proj
6767
|----------|----------|-------------|
6868
| [AGENTS.md](../AGENTS.md) | `.github-minimum-intelligence/` | Agent identity — name, personality, and behavioral guidance. |
6969
| [PACKAGES.md](../PACKAGES.md) | `.github-minimum-intelligence/` | Runtime dependencies and required packages. |
70+
| [Local Chat](./local-chat.md) | `.github-minimum-intelligence/docs/` | Command reference for the terminal-based `bun run chat` REPL — CLI flags and all slash-commands. |
7071

7172
---
7273

‎.github-minimum-intelligence/docs/local-chat.md‎

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
1+
# Local Chat
2+
3+
> [Index](./index.md) · Command reference for the terminal-based Local Chat REPL.
4+
5+
Local Chat (`bun run chat`, implemented in [`lifecycle/local-chat.ts`](../lifecycle/local-chat.ts))
6+
runs the same agent identity used by the GitHub Actions flow — `AGENTS.md`,
7+
`.pi/settings.json`, and `.pi/skills/` — from a local terminal against a local
8+
or cloud LLM provider. Conversations are organized into **threads** with
9+
closed-world identity: thread IDs are allocated by the tool, and unknown
10+
references are rejected rather than auto-created on typos.
11+
12+
This document lists the help for **all** commands: the command-line (CLI) flags
13+
you pass when launching, and the slash-commands available inside the interactive
14+
REPL.
15+
16+
---
17+
18+
## Command-line usage
19+
20+
Invoke with `bun run chat` from the `.github-minimum-intelligence` directory.
21+
22+
| Invocation | Description |
23+
|------------|-------------|
24+
| `bun run chat` | Interactive launcher (pick an existing thread or create one). |
25+
| `bun run chat --new [--name <alias>]` | Create a new thread and enter the REPL. |
26+
| `bun run chat --thread <id\|alias> [prompt...]` | Continue a thread; enter the REPL if no prompt is given, otherwise send the prompt one-shot. |
27+
| `bun run chat --list` | List all threads. |
28+
| `bun run chat --rm <id\|alias>` | Delete a thread mapping. |
29+
| `bun run chat --help` | Show the CLI help message. |
30+
31+
Short flags: `--thread`/`-t`, `--list`/`-l`, `--help`/`-h`.
32+
33+
### Environment overrides
34+
35+
These environment variables take the highest precedence (over `.pi/settings.json`
36+
and built-in defaults):
37+
38+
| Variable | Description |
39+
|----------|-------------|
40+
| `LOCAL_PROVIDER` | Override `.pi/settings.json` `defaultProvider`. |
41+
| `LOCAL_MODEL` | Override `defaultModel`. |
42+
| `LOCAL_THINKING` | Override `defaultThinkingLevel` (e.g. `low`, `medium`, `high`). |
43+
| `LOCAL_LLM_BASE_URL` | OpenAI-compatible base URL (LM Studio, Ollama, vLLM). Forwarded to `OPENAI_BASE_URL` with a placeholder API key. |
44+
45+
Precedence for provider/model: `LOCAL_*` env vars > `.pi/settings.json` >
46+
built-in defaults.
47+
48+
---
49+
50+
## REPL commands
51+
52+
Inside a running chat session, lines beginning with `/` are commands; anything
53+
else is sent to the model as a prompt. Type `/help` at any time to print the
54+
full list. Commands are grouped below exactly as `/help` presents them.
55+
56+
### Thread
57+
58+
Closed-world identity — IDs are allocated by the tool.
59+
60+
| Command | Description |
61+
|---------|-------------|
62+
| `/list` | List all threads. |
63+
| `/new [name]` | Create a new thread and switch to it. Optional alias must start with a letter (letters/digits/`_`/`-`, max 64). |
64+
| `/switch <id\|alias>` | Switch to an existing thread. An unknown reference is an error (no auto-create). |
65+
| `/history` | Condensed view of this thread's conversation. |
66+
| `/export md` | Export this thread as a Markdown file (written under the sessions directory). `/export` alone behaves the same. |
67+
| `/rename <name>` | Attach or replace this thread's alias. The name must be unique and match the alias grammar. |
68+
69+
### Model & config
70+
71+
| Command | Description |
72+
|---------|-------------|
73+
| `/status` | Show provider, resolved `pi --provider`, model, thinking level, thread, session turns/size, git branch, memory count, toggles (timing, verbose, auto-retry), uptime, and `OPENAI_BASE_URL` if set. |
74+
| `/model <name>` | Switch the model for subsequent turns. With no argument, prints the current `provider:model`. |
75+
| `/model <prov>:<name>` | Switch provider and model at once (e.g. `/model lmstudio:google/gemma-4-31b`). Re-wires local-server env vars for known local brands. |
76+
| `/provider <name>` | Switch provider (`lmstudio`, `ollama`, `vllm`, `openai`, …). With no argument, prints the current provider and known brands. Selecting a local brand re-wires the base URL and enables auto-retry. |
77+
| `/time` | Toggle the elapsed-time display. |
78+
| `/verbose` | Toggle verbose mode (JSONL event counts). |
79+
| `/auto-retry [on\|off\|N]` | Toggle auto-retry, or set the maximum number of attempts. `N` must be `1`–`10`; `off`/`0` disables it. With no argument, toggles the current state. |
80+
81+
### Memory log
82+
83+
| Command | Description |
84+
|---------|-------------|
85+
| `/remember <text>` | Append a timestamped entry to `memory.log`. |
86+
| `/memories [term]` | Search `memory.log` for `term`, or show the 10 most recent entries when no term is given. |
87+
88+
### Files & repo
89+
90+
| Command | Description |
91+
|---------|-------------|
92+
| `/cat <path>` | Display a file with line numbers. Paths are restricted to inside the repository. |
93+
| `/md <path>` | Render a Markdown file. Paths are restricted to inside the repository. |
94+
| `/git` | Show `git status --short` plus a `git diff --stat` summary. |
95+
| `/diff [path]` | Show `git diff`, optionally scoped to a path. |
96+
| `/run <command>` | Run a shell command (30-second timeout). |
97+
98+
### Prompt
99+
100+
| Command | Description |
101+
|---------|-------------|
102+
| `/retry` | Re-send the last prompt in this thread. |
103+
| `/again` | Create a new thread and re-send the last prompt. |
104+
| `/best-of <n>` | Send the last prompt `n` times (`n` = 2–10) in fresh throwaway threads and compare the responses. |
105+
| `/multiline` | Enter multiline input mode; type freely and submit with a blank line. |
106+
107+
### General
108+
109+
| Command | Description |
110+
|---------|-------------|
111+
| `/clear` | Clear the screen. |
112+
| `/help` | Print the full command list. |
113+
| `/exit`, `/quit` | End the chat session (Ctrl-C also quits at any time). |
114+
115+
---
116+
117+
## Notes
118+
119+
- Provider brands `lmstudio`, `ollama`, and `vllm` are treated as OpenAI-compatible
120+
local servers; switching to one auto-fills its default base URL
121+
(`http://localhost:1234/v1`, `http://localhost:11434/v1`, `http://localhost:8000/v1`
122+
respectively) and enables auto-retry.
123+
- Session transcripts are written by `pi` into `state/sessions/` and preserved
124+
per thread; `/history` and `/export md` read from them.
125+
- Unknown slash-commands print `Unknown command: <cmd> (type /help)` rather than
126+
being sent to the model.
127+
128+
---
129+
130+
*Generated from the command help in [`lifecycle/local-chat.ts`](../lifecycle/local-chat.ts).*

0 commit comments

Comments
 (0)