GitHub - patrickjh/ssa: Simple Shell Agent - an AI agent written in mostly POSIX shell. · GitHub
/" data-turbo-transient="true" />
Skip to content
Search or jump to...
Search code, repositories, users, issues, pull requests...
-->
Search
Clear
Search syntax tips
Provide feedback
--><br>We read every piece of feedback, and take your input very seriously.
Include my email address so I can be contacted
Cancel
Submit feedback
Saved searches
Use saved searches to filter your results more quickly
-->
Name
Query
To see all available qualifiers, see our documentation.
Cancel
Create saved search
Sign in
/;ref_cta:Sign up;ref_loc:header logged out"}"<br>Sign up
Appearance settings
Resetting focus
You signed in with another tab or window. Reload to refresh your session.<br>You signed out in another tab or window. Reload to refresh your session.<br>You switched accounts on another tab or window. Reload to refresh your session.
Dismiss alert
{{ message }}
patrickjh
ssa
Public
Notifications<br>You must be signed in to change notification settings
Fork
Star
main
BranchesTags
Go to file
CodeOpen more actions menu
Folders and files<br>NameNameLast commit message<br>Last commit date<br>Latest commit
History<br>12 Commits<br>12 Commits
bin
bin
libexec/ssa
libexec/ssa
markdownForAgents
markdownForAgents
.gitattributes
.gitattributes
LICENSE
LICENSE
README.md
README.md
View all files
Repository files navigation
ssa — Simple Shell Agent
A simple AI coding agent written in less than 1,000 lines of mostly<br>POSIX sh shell scripts. You give it a task in plain<br>English; it asks a model what shell commands to run, runs them, shows the<br>model the output, and repeats until the job is done.
Inspired by mini-swe-agent:<br>shell only , fresh process each step , simple loop .
Quick start
Clone the repo, set some environment variables and you're good to go:
export PATH="/path/to/ssa/bin:$PATH"
export OPENAI_API_KEY="sk-..."<br>export OPENAI_URL="https://openrouter.ai/api/v1/chat/completions"<br>export SSA_MODEL_RUNNER="/path/to/ssa/libexec/ssa/curlRunner.sh"<br>export SSA_MODEL="openrouter/auto"
cd /path/to/your/project<br>ssa summarize this repo
Run ssa -h for all options.
Dependencies
The core agent loop is written in pure POSIX sh<br>This core code only uses POSIX sh, date, grep, sed, and tee.<br>But to get replies from a model you need some non POSIX tools:
The bundled HTTP runner (curlRunner.sh) queries OpenAI compatible APIs<br>This depends on curl and jq
The bundled local AI runner (llamaCppRunner.sh) uses llama.cpp<br>Their llama-completion tool must be on your PATH
Those tools should all work fine on Linux, macOS, and BSD, but that is why<br>this is called "Mostly POSIX sh". POSIX sh except getting model results.
How the agent works (short version)
You pass a task on the command line (or pipe it on stdin).
The agent sends a transcript with the task to your model.
The model replies with a small shell script to help with the task.
The agent runs that script in your current directory
The agent feeds the output from that command back to the model.
Repeat until the model signals it is done.
Safety
By default, ssa runs model-generated shell commands as your user , with<br>your environment , in whatever directory you run it from.<br>Treat it like handing your terminal to the model.
You can apply sandboxing using --script-runner or SSA_SCRIPT_RUNNER.<br>These take a file path to a "Script Runner".<br>That Script Runner file will be executed and passed the script the AI model wants to run on stdin.<br>These Script Runner files are supposed to apply sandboxing, run the<br>script the model sent, and then send the stdout and stderr from running that<br>script back to the AI agent harness to be sent to the terminal and model.
Two "Script Runners" that apply simple sandboxing are included:
libexec/ssa/askUserSandbox.sh — ask the user before running each script<br>libexec/ssa/switchUserSandbox.sh — run scripts as another Unix user
Serious usage may want to create more complex sandboxes for the scripts<br>the AI model wants to run using seccomp / namespaces / pledge() / jails etc.
Debugging
Session files are written under $TMPDIR/ssa-$LOGNAME-/. Pass<br>--keep-session to keep them after exit. We try to log a lot of the files<br>created by the agent harness and sandbox so you can debug the various steps.<br>A good starting point is sessionTranscript.txt which shows the run of the agent<br>harness from the view of the model.
Models
The smallest AI models can struggle to use this as they do not really respond<br>with answers that can be parsed by our simple parsing logic. Specifically,<br>I failed to get usable results when doing some simple tests with Qwen 2.5 - 1.5B<br>and Qwen 2.5 - 3B models. However, models such as Qwen 2.5 - 7B and Qwen 2.5 - 32B<br>were able to produce results that could be parsed into runnable shell scripts<br>for very simple "hello world" type tasks. So just be aware this might not work<br>with the smallest models.
License
MIT — see LICENSE.
About
Simple...