Shell Routines

Shell scripting toolkit for Claude Code and OpenCode — automated scaffolding, best practices, and quality enforcement.

Prerequisites

| Tool | Purpose | | -------------------- | --------------------------- | | bash-language-server | LSP server for Bash | | shellcheck | Static analysis and linting | | shfmt | Code formatting | | bashunit | Test execution | | checkbashisms | POSIX compatibility checks | | hyperfine | Statistical benchmarking |

# macOS
npm i -g bash-language-server
brew install shellcheck shfmt bashunit checkbashisms hyperfine

# Ubuntu/Debian
npm i -g bash-language-server
sudo apt install shellcheck shfmt bashunit checkbashisms hyperfine

# Arch Linux
npm i -g bash-language-server
sudo pacman -S shellcheck shfmt bashunit checkbashisms hyperfine

Installation

Claude Code:

/plugin marketplace add objctp/shell-routines
/plugin install shell-routines@objct-plugins

# Local development
git clone https://github.com/objctp/shell-routines && cd shell-routines && claude

OpenCode:

Add to your config — OpenCode auto-installs npm plugins via Bun at startup.

// Project scope: opencode.json
{ "plugin": ["@objctp/opencode-shell-routines"] }

// Global scope: ~/.config/opencode/opencode.json
{ "plugin": ["@objctp/opencode-shell-routines"] }

# Local development
git clone https://github.com/objctp/shell-routines && cd shell-routines
ln -s opencode .opencode   # temp symlink so OpenCode discovers the source (don't commit)
opencode

How the OpenCode plugin registers its content: OpenCode loads only the plugin's server entrypoint from the npm package, so on first load the plugin copies its bundled agents/ commands/ skills/ scripts/ into ~/.config/opencode/, where OpenCode's scanners discover them. Restart OpenCode once after installing for skills, commands, and agents to register. The copies are re-synced automatically when the package version changes (overwriting the synced files) — to customise, edit copies under your project's .opencode/ instead. For project-local scope, configure the plugin with options:

{ "plugin": [["@objctp/opencode-shell-routines", { "scope": "project" }]] }

Components

| Component | Purpose | Trigger | | ------------ | ------------------------------------------ | --------------------------------- | | Hooks | Validation and formatting after file edits | Automatic on .sh, .bash, etc. | | Skills | Best practices, patterns, and scaffolding | Context or manual (/skill-name) | | Commands | Interactive tools | Manual only (/command-name) | | Agents | Specialised subagents for complex tasks | Auto-spawned |

Skills

| Skill | When to Use | Purpose | | ------------------------ | ----------------------------------------- | ---------------------------------------- | | shell-best-practices | Writing or creating bash scripts | Standards enforcement + scaffolding | | shell-debugging | Script has runtime failures | Systematic troubleshooting | | shell-security | Auditing for security vulnerabilities | Destructive commands, credentials, fixes | | shell-test | Generating tests | Creates bashunit test files | | shell-review | Quality review of a working script | Structured assessment | | shell-batch-operations | Processing 100+ items or multi-stage work | Token-efficient multi-file processing | | shell-profiling | Script works but runs slowly | Benchmarking and bottleneck analysis |

Commands

| Command | Purpose | | ---------------------------- | ------------------------------------------------------- | | /shell-new <path> [type] | Create new script (delegates to shell-best-practices) | | /shell-test-run [path] | Run tests using bashunit | | /shell-audit <path> | Quality audit (delegates to shell-review skill) | | /shell-batch-exec <script> | Execute batch script and parse JSON output | | /shell-routines-setup | Configure bash-language-server, ShellCheck, shfmt |

Agents

| Agent | Purpose | | ----------------- | ------------------------------------------------------- | | shell-architect | Design complex bash architecture (read-only, no writes) | | shell-expert | Deep implementation work following skill standards |

Templates

Located in skills/shell-best-practices/assets/:

| Template | Use For | | ------------- | ----------------------------------------------- | | standard.sh | Most scripts (argument parsing, error handling) | | minimal.sh | Simple one-task utilities | | library.sh | Sourced libraries (no direct execution) | | posix.sh | POSIX-compatible scripts (containers, embedded) |

License

MIT

Related Documentation

• ARCHITECTURE.md — Internal architecture