ShellMan | Your AI coding sidecar
ShellMan | Your AI coding sidecar

Appearance

CLI Guide ​

This page covers the shellman command line interface.

Install ​

bash
npm install -g shellman

Quick Start ​

Start local runtime:

bash
shellman serve

Start local runtime and open browser automatically:

bash
shellman serve -o

Command Overview ​

Show help:

bash
shellman --help

Serve runtime:

bash
shellman serve --help

Run DB migration:

bash
shellman migrate up

serve Options ​

  • --host <value> local listen host
  • --port <value> local listen port
  • --open, -o open browser after local server starts
  • --config-dir <value> shellman config directory
  • --tmux-socket <value> tmux socket path
  • --webui-dist-dir <value> web ui dist directory
  • --pid <value> pid file path for serve singleton

Common Usage Patterns ​

Run on all interfaces:

bash
shellman serve --host 0.0.0.0 --port 8000

Use custom config directory:

bash
shellman serve --config-dir /path/to/config

Use custom pid file:

bash
shellman serve --pid /tmp/shellman.pid

Use custom tmux socket:

bash
shellman serve --tmux-socket /tmp/tmux-shellman.sock

Notes ​

  • serve is singleton-protected by a pid file.
  • Default pid file path is inside your config directory.
  • If another serve instance is running, startup will fail with a pid lock error.

AGENTS-SIDECAR Lookup Strategy ​

For task-completion AI context, Shellman resolves AGENTS-SIDECAR.md in this order:

  1. Repository-local file (highest priority): <repo>/AGENTS-SIDECAR.md
  2. Global fallback file: ~/.config/shellman/AGENTS-SIDECAR.md

If both exist, the repository-local file is used first.

Example AGENTS-SIDECAR.md ​

md
# AGENTS-SIDECAR

You are a **coordinator**.  
Avoid doing concrete implementation work directly whenever possible.

Your primary responsibility is to:
- collect context from one Codex process,
- pass the right information to another Codex process,
- keep all processes aligned on the same task state.

## Role Boundaries

- Prefer coordination over execution.
- Delegate coding, script execution, and deep file operations to Codex agents.
- Communicate with Codex agents in natural language.

## Terminal Awareness (Critical)

Always watch the current terminal state before sending any input.  
Never type blindly.

## Mode Switching

If you are in bash/zsh mode, run:

```bash
codex -s danger-full-access
```

to enter Codex mode.

## Tool Preference by Mode

- In **Codex mode**, prefer using `input_prompt`.
- In **shell mode**, prefer using `exec_command`.

## Status Message Rule

When setting `flag.status_message`:
- keep it within **50 characters**.