simse is built around a set of components that work together to provide an agentic coding assistant. This page describes each component from a user and integrator perspective.
A session is a persistent conversation between you and simse. Sessions track the full message history, tool call results, and any decisions made during the interaction.
Sessions support:
List your saved sessions with the simse resume CLI subcommand, and resume one inside the TUI with /resume.
Backends are the LLM providers that power simse's reasoning. simse communicates with backends using the Agent Client Protocol (ACP), which standardizes session management, streaming, tool calls, and permission flows.
You can configure multiple backends with different endpoints, API keys, and timeouts. Each backend entry in your configuration specifies:
Tools are the capabilities simse uses to interact with your codebase and environment — reading files, writing code, running shell commands, searching, and more.
Tools come from two sources:
Tools are namespaced to avoid collisions: MCP tools appear as {server-name}/{tool-name}. Use /mcp to see connected MCP servers and the tools they expose, along with their status.
Tool output is capped at a configurable character limit (default 50,000). Per-tool overrides are available. Truncated output includes a notice indicating how many characters were omitted.
The library is simse's persistent memory. It stores context, notes, and knowledge that persists across sessions. You can search, add, prune, and reindex library entries.
Key commands:
| Built-in tool | Description |
|---|---|
library_search | Find entries by keyword or semantic similarity |
library_withdraw | Remove a specific entry by ID |
library_catalog | Browse all topics in the library |
library_compact | Summarize a topic into a compact form |
The library has a capacity limit. When the limit is reached, use library_withdraw to remove entries to free space.
The sandbox controls how simse interacts with your filesystem and shell. It provides:
The sandbox ensures simse operates within the boundaries you define, preventing unintended changes outside your project.
Hooks let you run commands automatically when specific tools are called. They are defined per-plugin in a hooks.toml file inside the plugin's directory.
Each hook has two fields:
fs_write|fs_edit)${PLUGIN_ROOT} is replaced with the plugin's directory path.When simse calls a tool, it checks all loaded plugins for hooks with a matching matcher pattern and runs the corresponding command. See the Hooks guide for examples.
Permissions control which tool operations simse can perform without asking. simse supports four permission modes:
| Mode | Behavior |
|---|---|
| Default | Ask for confirmation on sensitive operations |
| Accept edits | Auto-accept file edits, ask for other operations |
| Plan | No tool execution — planning mode only |
| Don't ask | Execute all tools without confirmation |
Fine-grained control is available through glob rules that match tool names and argument patterns. Rules are evaluated in order; the first match wins:
{
"rules": [
{
"tool": "write_file",
"pattern": "/home/user/projects/**",
"action": "allow"
}
]
}When simse asks for permission, you can choose:
| Decision | Effect |
|---|---|
| Allow once | Permit this specific invocation only |
| Allow always | Permit this tool for the rest of the session |
| Reject once | Deny this specific invocation |
| Reject always | Deny this tool for the rest of the session |
"Always" decisions are remembered for the current session only and are not carried across sessions.
simse provides interactive slash commands for managing your session:
| Command | Description |
|---|---|
/help | List available commands |
/status | Show session and connection status |
/resume | Resume a previous session |
/compact | Manually trigger session compaction |
Additional commands are available depending on your configuration and client.