1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
|
# llsh
`llsh` is a statically linked terminal LLM agent for Linux. It supports
OpenAI-compatible APIs, Anthropic, Ollama, shell and file tools, session
history, skills and memories from `.agents/`, and optional MCP servers.
## Build
The repository includes source archives for curl, OpenSSL, zlib, cJSON, and
nlohmann/json. The host GCC toolchain builds their static archives. On x86_64
Fedora, install GNU Make, GCC/G++, Perl, `rpm`, `dnf`, `rpm2cpio`, and `cpio`,
and allow access to Fedora repositories. The build downloads matching
`glibc-static` and `libstdc++-static` RPMs into the ignored build directory;
it does not install packages system-wide. Then run:
```sh
make
```
The default build creates a statically linked `./llsh` executable. To build
and run the test suite:
```sh
make test
```
Optional checks are `make asan` (requires Clang) and `make valgrind` (requires
Valgrind). If static glibc/libstdc++ packages are unavailable, run tests with
the host shared runtimes:
```sh
make STATIC=0 test
```
`make clean` removes application/test outputs; `make vendor-clean` removes
generated third-party archives so they can be rebuilt from the bundled
sources.
## Configure a model
The simplest invocation supplies a provider and its credentials:
```sh
./llsh --provider openai --api-key "$OPENAI_API_KEY" "Explain this project"
```
The CLI supports `openai`, `anthropic`, and `ollama`. OpenAI-compatible
endpoints can be selected with `--base-url`; Ollama defaults to
`http://localhost:11434` and does not require an API key.
For repeat use, configure `.agents/models.json` with a default preset:
```json
{
"default": "work",
"presets": {
"work": {
"provider": "openai",
"model": "gpt-5.2",
"api_key": "replace-with-a-key"
}
}
}
```
Keep credentials out of committed project files. CLI options override preset
values. See `./llsh --help` for the complete list of options.
When started without a prompt in a terminal, `llsh` opens an interactive REPL.
With a prompt argument, it runs one turn and exits:
```sh
./llsh "Summarize the files in this directory"
```
The interactive commands include `/help`, `/model`, `/agent`, `/save`,
`/export`, `/compact`, and `/exit`. The shell can be entered with Backtab.
## Tools and workspace configuration
The built-in tools are `read_file`, `write_file`, `run_shell`, `use_skill`,
`search_memories`, `embed`, `llm`, and `compact`. File and shell operations
use the process working directory; `-C, --cwd` selects it.
Model presets in `.agents/models.json` configure model connections and model
limits; they do not configure shell policy. Put llsh runtime tool settings in
`.agents/speakmcp-settings.json` instead:
```json
{
"shell_allowlist": ["git", "rg", "cat"],
"shell_denylist": ["git push", "rm"],
"confirm_destructive": true,
"shell_timeout_secs": 45,
"max_output_chars": 9000,
"max_file_bytes": 700000
}
```
The global `~/.agents/speakmcp-settings.json` values are shallow-merged with
workspace settings; workspace keys override global keys. Explicit CLI shell
policy and limit flags override settings.
llsh is not a sandbox: tool calls run with the current user's permissions,
and absolute file paths are accepted. Shell command allow/deny policies can
be supplied with repeatable CLI options. Destructive-command confirmation is
available in the interactive REPL:
```sh
./llsh --shell-allow git --shell-allow rg --shell-deny git\ push \
--confirm-destructive "Inspect the repository"
```
The destructive-command detector is heuristic; use an operating-system
sandbox when commands must be restricted to a security boundary.
Workspace and global agent configuration can be loaded from `.agents/` and
`~/.agents/`. Supported content includes `agents.md`, `system-prompt.md`,
`models.json`, MCP server configuration, skills, sub-agent profiles, tasks,
and memories. MCP server commands are not started unless explicitly trusted:
```sh
./llsh --allow-mcp "Use the configured project tools"
```
MCP tools are exposed with qualified names of the form
`mcp__<server-name-length>_<server-name>__<tool-name>`. Use that name in a
sub-agent's tool allowlist.
## Platform and release scope
The build targets x86_64 Linux and uses the host glibc ABI. Although linked
statically, glibc's name-service lookups can load NSS shared libraries at
runtime; use the matching glibc runtime on the target system. HTTPS requests
also require a usable system CA certificate bundle. Other platforms and
architectures are not currently supported by the build.
Third-party components and their license families are listed in
[`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).
## License
The llsh project is licensed under the MIT License; see [`LICENSE`](LICENSE).
|