# 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).