Simple Shell Agent (ssa)

ssa is a simple AI agent in one POSIX sh file. Inspired by mini-swe-agent: give the model only shell, run each step in a fresh process, keep a simple loop. Feels like a unix util.

Requirements

• POSIX sh, plus curl and jq on PATH
• Linux and macOS work as usual; on Windows use WSL (ssa targets POSIX systems only)
• A chat-completions URL in SSA_URL. Curl POSTs the OpenAI-style body there; the path need not end in /chat/completions.

Any OpenAI-compatible endpoint works (OpenAI, local proxies, and similar providers). Set SSA_KEY when the provider requires auth.

Install

git clone https://github.com/patrickjh/ssa.git
cd ssa
chmod +x ssa
export PATH="$PWD:$PATH"

Or download the ssa file alone, chmod +x, and put its folder on PATH.

Try it

export SSA_KEY="sk-..."
export SSA_URL="https://api.openai.com/v1/chat/completions"
export SSA_MODEL=gpt-4o-mini
ssa summarize this repo

Task on stdin:

echo "summarize this repo" | ssa

Batch / no TTY: SSA_NO_ASK=1. Keep temp logs: SSA_KEEP_TEMP=1. Extra request fields (think, max_tokens, sampling): SSA_REQUEST_JSON.

Unix-shaped. Handle cd, env, and redirects in the shell. Script output streams live on stdout. Agent messages (ask UI, errors, final status) go to stderr.

Local models

Point SSA_URL at llama.cpp (or another server that honors think: false). ssa does not default that; pass it in SSA_REQUEST_JSON. Local max_tokens defaults are often 256–2048 and will truncate write requests.

export SSA_URL=http://127.0.0.1:8080/v1/chat/completions
export SSA_MODEL=gemma-4-31b
export SSA_REQUEST_JSON='{"think":false,"max_tokens":8192,"temperature":1,"top_p":0.95}'
export SSA_KEEP_TEMP=1
export SSA_MAX_MODEL_PROMPTS=30
ssa fix the failing test

Add SSA_NO_ASK=1 when there is no TTY.

Safety

ssa runs shell scripts written by the model in your current directory. Treat that like handing the model your terminal.

• Ask-user approval is on by default — each model script is shown on stderr; you approve from /dev/tty ([Y]es / [N]o / [Q]uit).
• Scripts run with sh on stdin. Writes and edits are harness file I/O after the same ask. Hung scripts are not killed; wrap ssa with timeout (or a container / other user) in your shell.

Docs

• Full usage and defaults: ssa -h
• Design and coding style for contributors and coding agents: AGENTS.md

Tests

sh tests/runTests.sh

That is the only supported entry point. Do not run *.test.sh files alone.

Layout

ssa/
├── AGENTS.md   # design + style for coding agents
├── LICENSE
├── README.md   # this file
├── ssa         # the agent (single file)
└── tests/      # live stories; sh tests/runTests.sh

License

MIT — see LICENSE.