# How to Use the symsh Neuro-Symbolic Shell: A Complete Guide

> Master symsh, the neuro-symbolic shell from SymbolicAI. This guide shows you how to blend OS commands with LLM queries for powerful AI-driven workflows.

- Repository: [ExtensityAI/symbolicai](https://github.com/extensityai/symbolicai)
- Tags: how-to-guide
- Published: 2026-03-01

---

**The symsh neuro-symbolic shell is an interactive command-line interface in SymbolicAI that combines traditional OS shell commands with large language model (LLM) queries using special prefixes like `'`, `.`, and `?`.**

The symsh neuro-symbolic shell is the flagship interactive interface of the SymbolicAI framework (extensityai/symbolicai), designed to blur the line between conventional system administration and AI-assisted reasoning. By embedding LLM capabilities directly into a familiar shell environment, symsh allows developers to execute Python scripts, manage files, and query neural models from a single, context-aware prompt.

## Core Architecture of symsh

The shell is implemented primarily in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py), with several specialized components handling distinct responsibilities:

| Component | Role | Source Location |
|-----------|------|---------------|
| **Prompt loop** | Reads user input, builds a rich prompt (git branch, conda env, cwd) and dispatches the command. | `listen()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) |
| **Command dispatcher** | Normalises Windows-specific aliases, handles built-in `symsh` meta-commands, then routes to the appropriate handler. | `process_command()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) |
| **LLM request detector** | Decides whether a token sequence should be sent to the LLM (`'`, `"`, `` ` ``) or to the internal search engine (`?`). | `is_llm_request()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) |
| **LLM query engine** | Builds a prompt, selects the configured `Function` (or `Conversation` for stateful chats), runs the LLM and returns the result. | `query_language_model()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) |
| **Stateful conversation manager** | Persists conversation state in `~/.conversation_state` and reloads it for `.`-prefixed queries. | `_process_new_conversation()`, `_process_followup_conversation()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) |
| **Search integration** | Forwards `?`-prefixed queries to a configured serpapi search interface. | `search_engine()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) |
| **Configuration** | Reads [`symsh.config.json`](https://github.com/extensityai/symbolicai/blob/main/symsh.config.json) (merged from user home, environment, and project directories) to control colors, plugin prefixes, and splash-screen display. | `_start_symai()` in [`symai/__init__.py`](https://github.com/extensityai/symbolicai/blob/main/symai/__init__.py) |
| **Help documentation** | The markdown file [`symsh.md`](https://github.com/extensityai/symbolicai/blob/main/symsh.md) contains the concise usage reference that the shell prints for `man symsh`. | [`symai/symsh.md`](https://github.com/extensityai/symbolicai/blob/main/symai/symsh.md) |

The dispatcher first maps Windows-specific commands (`ls → dir`, `rm → del`, etc.) via `map_nt_cmd()`, then checks for plugin commands (`set-plugin`, `unset-plugin`, `get-plugin`). After that it determines whether the input is an LLM request, a search request, a retrieval-augmented indexing (`*`), a conda environment switch, directory navigation, or a plain OS command.

## Command Prefixes Reference

Understanding the prefix system is essential for effective use of the symsh neuro-symbolic shell. The wrapper characters (`'`, `"`, `` ` ``) have no functional difference; they simply delimit the query string for the parser.

| Prefix | Mode | Effect |
|--------|------|--------|
| **`'`**, **`"`**, **`` ` ``** | *Normal* | Sends the wrapped text as a single-shot LLM query and prints the response. |
| **`.`** (`.'`, `."`, `.`) | *Stateful* | Starts (or continues) a persistent conversation stored on disk; subsequent `.` queries reuse the same context. |
| **`!`** (`!'`, `!"`, `!`) | *Overwrite* | Works like normal/stateful but re-creates the conversation state file, discarding previous history. |
| **`?`** (`?'`, `?"`, `?`) | *Search* | Sends the query to the internal search engine (SerpAPI) and returns the top results. |
| **`*`** | *Retrieval-augmented indexing* | Indexes a file, directory, git repo, or arXiv PDF for later RAG queries (see `retrieval_augmented_indexing()`). |
| **`set-plugin <module>`**, **`unset-plugin`**, **`get-plugin`** | *Plugin management* | Sets a default plugin that will be invoked automatically for LLM queries. |
| **`conda activate <env>`**, **`conda deactivate`** | *Conda environment switching* | Temporarily changes the Python exec prefix used for subsequent subprocesses. |

## Quick Start Guide

Launch the symsh neuro-symbolic shell by running:

```bash
symsh

```

You will see a colored prompt similar to:

```

/home/user <b>project</b> conda:[base] symsh:>

```

### Simple LLM Query (Normal Mode)

Use single quotes, double quotes, or backticks to send a one-time query to the language model:

```bash
'Explain the difference between a list and a tuple in Python.'

```

The result prints directly beneath the prompt.

### Stateful Conversation (Stateful Mode)

Prefix your query with a dot to start a persistent conversation stored in `~/.conversation_state`:

```bash
.'Give me a short summary of Newton's laws.'

```

Subsequent dot-prefixed queries continue the same thread:

```bash
.'How do those laws apply to a satellite in orbit?'

```

### Overwrite Existing Conversation (Overwrite Mode)

Use the exclamation mark to discard previous history and start fresh:

```bash
!'What is the capital of France?'

```

This invokes `_process_new_conversation()` in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) with the overwrite flag set, deleting the existing state file before creating a new one.

### Web Search (Search Mode)

Prefix with a question mark to query the search engine:

```bash
?'Best practices for Dockerfile multi-stage builds'

```

The `search_engine()` function in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py) forwards this to the configured SerpAPI interface.

### Index a Directory for RAG

Use the asterisk prefix to index content for retrieval-augmented generation:

```bash
*index:/home/user/docs/project

```

This triggers `retrieval_augmented_indexing()` to ingest files into a vector store. Subsequent LLM queries automatically retrieve relevant chunks from the indexed content.

### Use a Plugin

Set a default plugin to customize LLM behavior:

```bash
set-plugin my_custom_style
'Write a haiku about clouds.'

```

The plugin persists for the session and is applied via the plugin management handlers in `process_command()`.

### Chaining Commands

Combine LLM queries with shell commands using `&&`:

```bash
'List the top 3 Python packages on PyPI' && echo "Done"

```

If the first part is an LLM request, its result pipes into the subsequent command.

### Platform-Specific Command Mapping

On Windows, `symsh` automatically translates Unix commands to their Windows equivalents via `map_nt_cmd()`:

```bash
ls -R

```

Internally, this becomes `dir /s` before execution, allowing seamless cross-platform usage without memorizing Windows-specific syntax.

## Advanced Configuration

The symsh neuro-symbolic shell reads configuration from [`symsh.config.json`](https://github.com/extensityai/symbolicai/blob/main/symsh.config.json), merged hierarchically from user home, environment, and project directories. Key settings controlled via `_start_symai()` in [`symai/__init__.py`](https://github.com/extensityai/symbolicai/blob/main/symai/__init__.py) include:

- **Colors and theming**: Customize the prompt appearance
- **Plugin prefixes**: Define custom command prefixes
- **Splash screen**: Toggle the ASCII art display on startup

For custom LLM behaviors, launch with:

```bash
symsh --conversation-style path.to.Module

```

This loads a module providing a custom `Function` class for stylized prompts or temperature settings.

Enable automatic error analysis with:

```bash
symsh --auto-query-on-error

```

When a subprocess fails, the shell extracts the error text and queries the LLM for explanations via `query_language_model()`.

## Summary

- **symsh** is the interactive neuro-symbolic shell of SymbolicAI, merging OS commands with LLM queries in a unified interface implemented in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py).
- Use **single quotes, double quotes, or backticks** for one-shot LLM queries; prefix with **`.`** for stateful conversations stored in `~/.conversation_state`.
- **Overwrite** existing sessions with `!` to discard history, or **search the web** with `?` via the integrated SerpAPI interface.
- **Index documents** for RAG using the `*` prefix, enabling retrieval-augmented responses to subsequent queries.
- Configure behavior through [`symsh.config.json`](https://github.com/extensityai/symbolicai/blob/main/symsh.config.json) and extend functionality via plugins using `set-plugin` and custom conversation styles.

## Frequently Asked Questions

### How do I start a persistent conversation in symsh?

Prefix your query with a dot (`.`) to enter stateful mode. This creates a conversation file at `~/.conversation_state` that persists across sessions. For example, `.'Explain quantum computing'` starts the thread, and subsequent `.` queries continue the same context. Use `!` instead of `.` to overwrite and start fresh.

### What is the difference between single quotes, double quotes, and backticks in symsh?

There is no functional difference between `'`, `"`, and `` ` ``. All three delimiters serve the same purpose: marking the enclosed text as an LLM query rather than a shell command. Choose whichever delimiter avoids conflicts with your query content. For instance, use double quotes if your query contains single apostrophes.

### How does symsh handle Windows commands?

The shell automatically maps Unix-style commands to Windows equivalents via the `map_nt_cmd()` function in [`symai/shellsv.py`](https://github.com/extensityai/symbolicai/blob/main/symai/shellsv.py). When running on Windows, commands like `ls` are internally translated to `dir`, `rm -rf` becomes `rmdir /s /q`, and similar mappings occur before execution. This allows seamless cross-platform usage without memorizing Windows-specific syntax.

### Can I use symsh for retrieval-augmented generation (RAG)?

Yes. Use the asterisk (`*`) prefix to index files, directories, git repositories, or arXiv PDFs via the `retrieval_augmented_indexing()` function. Once indexed, subsequent LLM queries automatically retrieve relevant chunks from the vector store to provide context-aware answers. For example, `*index:/path/to/docs` followed by `'What are the main design decisions?'` will query the indexed content.