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

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, 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
Command dispatcher	Normalises Windows-specific aliases, handles built-in symsh meta-commands, then routes to the appropriate handler.	process_command() in 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
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
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
Search integration	Forwards ?-prefixed queries to a configured serpapi search interface.	search_engine() in symai/shellsv.py
Configuration	Reads 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
Help documentation	The markdown file symsh.md contains the concise usage reference that the shell prints for man symsh.	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:

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:

'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:

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

Subsequent dot-prefixed queries continue the same thread:

.'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:

!'What is the capital of France?'

This invokes _process_new_conversation() in 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:

?'Best practices for Dockerfile multi-stage builds'

The search_engine() function in 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:

*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:

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 &&:

'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():

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, merged hierarchically from user home, environment, and project directories. Key settings controlled via _start_symai() in 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:

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:

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.
• 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 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. 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}