sigil-sh 0.1.0

Verb-first LLM interaction for the shell, with optional punctuation shortcuts.

Sigil

Natural-language shell assistant.

Sigil turns short terminal intents into explicit, inspectable shell actions. Ask from local context, authorize web search, propose one command, delegate one agent step, or pursue a bounded goal without leaving your prompt.

, find files over 10 MB in this repo excluding .git
,, run the relevant tests
? what changed in this repo?
?? what changed upstream in the latest release?
@ fix the failing parser test

Sigil is alpha software. It is ready for early shell users who are comfortable with local LLM tooling, explicit confirmations, and occasional interface changes.

Why Sigil?

Most shell assistants blur together three very different operations: suggesting, executing, and explaining. Sigil keeps those routes separate.

Need	Glyph	What happens
"Give me the command."	,	Proposes one command. Nothing runs.
"Do one agent turn."	,,	Runs one Pi invocation after confirmation.
"Do one routine turn."	,,,	Runs one Pi invocation without routine confirmation, within policy.
"Answer from local context."	?	Read-only answer with the read tool. No shell is exposed.
"Answer with web."	??	Read-only answer with read and web search tools.
"Work toward a goal."	@	Runs a bounded goal loop with checkpoints.
"Continue routinely."	@@	Runs a bounded goal loop with routine steps auto-approved within policy.

The result is a shell workflow with small blast radius, durable state, and a plain CLI underneath the punctuation.

Install

Install the Python command, then install the shell binding:

uv tool install sigil-sh
sigil install zsh
sigil doctor

For Bash:

uv tool install sigil-sh
sigil install bash
sigil doctor --shell bash

You can also install with pipx:

pipx install sigil-sh

To try the current main branch before a tagged release:

uv tool install git+https://github.com/rlouf/sigil

The Python package is named sigil-sh because sigil was not available as a distribution name. The installed command is still sigil.

sigil install copies the bundled binding to ~/.sigil/shell/<shell>/ and adds an idempotent source block to .zshrc or .bashrc. Running it again updates the binding without duplicating the rc block.

Requirements

• Python 3.11+

• zsh or Bash for shell bindings

• A local OpenAI-compatible chat completions endpoint for command generation and Pi-backed routes (default http://127.0.0.1:8080/v1/chat/completions)

• pi, the pi-mono coding-agent CLI, for ?, ??, ,,, ,,,, @, and @@. Only , works without it. Install it with:

  curl -fsSL https://pi.dev/install.sh | sh
  # or: npm install -g --ignore-scripts @earendil-works/pi-coding-agent
  

  Then point Pi at your model and confirm Sigil can see it with sigil doctor.

• glow for Markdown rendering, optional but recommended

Useful environment variables:

SIGIL_MODEL_URL=http://127.0.0.1:8080/v1/chat/completions
SIGIL_MODEL_NAME=local-model
SIGIL_MODEL_PATH=/path/to/model.gguf
SIGIL_STATE_DIR=$HOME/.sigil
SIGIL_ENABLE_PROMPT_MARKER=0
SIGIL_ENABLE_TURN_CAPTURE=0
SIGIL_GLOW_STYLE=notty
SIGIL_GLOW_WIDTH=88

Quick Start

Once the shell binding is installed, use the glyphs directly:

# Propose one command. In zsh, the command is inserted into the prompt buffer.
, find wav files larger than 50 MB

# Run one confirmed agent step.
,, run the relevant tests

# Ask from local read-only context.
? why did the last command fail?

# Ask with web search authorized.
?? what changed in the latest release?

# Pursue a goal with checkpoints.
@ fix the failing parser test

Use stdin as context:

git diff | ? review risky changes
git diff --name-only | , run the relevant tests

When stdin is piped into comma routes, Sigil previews the input and asks before using it. Question routes use piped input directly because they have no execute path.

A Typical Flow

# 1. Ask what changed.
? summarize this repo state

# 2. Ask for the smallest useful command.
, run the focused tests for this change

# 3. Let Sigil run exactly one action.
,, run the focused tests

# 4. Audit what happened.
sigil events
sigil events lineage

Sigil stores command suggestions, question answers, and act steps with alpha trust fields so you can inspect the route, mode, risk labels, and event inputs.

Glyph Reference

Installed zsh and Bash bindings expose these shortcuts:

Glyph	Name	Behavior
,	recommend	Recommend one command.
,,	step	Run one agent turn, confirming effects.
,,,	auto step	Run one agent turn, auto-approving routine effects within policy.
?	answer	Answer from local read-only context.
??	web answer	Answer from local context plus web search.
@	goal	Run a bounded goal loop with checkpoints.
@@	auto goal	Run a bounded goal loop with routine auto-approval.

Examples:

, find wav files
,, run the relevant tests
,,, fix the failing parser test
? why does git say this branch diverged?
?? what does the remote branch contain?
@ fix the failing parser test
@@ update docs and run checks

, prints a command proposal. The zsh binding puts it in the editable prompt buffer with print -z and records it in shell history. Bash records it in history. Proposals include terse risk labels such as network · publish.

,, asks before handing the objective to Pi, gives Pi read/search/edit/write tools, and returns control to the shell after one bounded Pi invocation. That invocation may include zero or more tool calls. ,,, runs the same one-turn route without routine confirmation. Bash calls inside those turns are blocked and handed off. @ and @@ repeat bounded Pi turns toward a durable goal until completion, blockage, budget exhaustion, or interruption. Agent steps always stream Pi's raw tool calls and prose through glow or cat; they do not replace the final answer with a compact summary.

Question routes do not expose Bash. If an answer recommends a command, it is plain answer text, not a tool call or terminal handoff.

To install the CLI without punctuation shortcuts:

sigil install zsh --no-glyphs

Trust Model

Sigil's important user rules are:

Route	Mode	Rule
,	propose	Model-authored proposal only.
,,	execute-write	One confirmed Pi agent step.
,,,	execute-write	One auto-approved Pi agent step within policy.
@	execute-write	Bounded goal loop with checkpoints.
@@	execute-write	Bounded goal loop with routine auto-approval.
?	read-only	Local answer route with no Bash tool.
??	read-only	Read plus web answer route with no Bash tool.

Trust records include route, mode, risk labels, and simple input event ids. Inspect them with:

sigil events
sigil events lineage

For details, see docs/trust-model.md.

CLI

The glyphs are thin shell functions over a regular CLI:

sigil command [--json] [PROMPT]
sigil events [--limit N] [--json] [--raw]
sigil events lineage [EVENT_ID] [--json]
sigil session [show|list|clear] [--json]
sigil status [--json]
sigil install {zsh|bash} [--install-dir DIR] [--rc FILE] [--glyphs|--no-glyphs]
sigil doctor [--shell auto|zsh|bash] [--json]

Copy-pasteable examples:

sigil command "find files over 10 MB in this repo excluding .git"
sigil command "show the largest directories"
git diff --name-only | sigil command "run the relevant tests"
sigil status
sigil events

See docs/cli.md for the user-facing CLI contract and JSON examples.

State

Sigil writes event-sourced state under ~/.sigil/ by default. Set SIGIL_STATE_DIR to move it.

Installed Bash and zsh bindings set SIGIL_SESSION_ID once when the shell starts, so separate terminal windows keep separate continuity. Override the boundary with SIGIL_SESSION_ID or SIGIL_SESSION_DIR.

Inspect state without calling a model:

sigil session show
sigil session list
sigil session clear
sigil events
sigil events lineage

Project Scope

Sigil is:

• A command-line tool and optional shell binding.
• A local-model command proposal route.
• A Pi-backed question and one-step edit route.
• An evented state layer for shell continuity and audit history.

Sigil is not:

• A public Python library. The Python package does not expose a supported API.
• A background autonomous agent.
• A replacement for reviewing commands and model output.

Development

Set up the repo:

uv sync --group dev

Run the checks used by CI:

uv run pre-commit run --all-files
uv run pytest

Render deterministic demo GIFs:

scripts/render-demo-gifs.sh

Demo tapes live in docs/demos. They run the real Sigil CLI from this checkout while shimming only external dependencies such as the model server, pi, and uv.

License

Apache-2.0. See LICENSE.