Agentic Workstation

Install · Architecture · Wiki · Integrations · Personal DX Stack · Docs · Contributing

agentic-workstation is an AI-first, chezmoi-managed workstation baseline that equips your machine with skills, agents, MCP servers, CLI helpers, and loop engineering primitives — ready to go in one command.

Works with Claude Code, Muse Code, opencode, Cursor, Gemini CLI, GitHub Copilot, and any AI coding tool that supports agent skills.

Thin workstation — this repository ships no embedded skills/*, loops/*, mcp/*, prompts/*, agents/*, or packs/teams. All capabilities are delegated to agent-toolkit via dots-skills install-toolkit (Homebrew / AUR agent-toolkit-bin / GitHub V binary / uv tool install --force 'agent-toolkit-cli>=1.11.0'). The SKILL.md catalog is provided by the toolkit at runtime. Workstation-only runner logic (dev-companion/runner) is retained. See docs/AGENT_TOOLKIT.md and docs/ARCHITECTURE.md.

What You Get

Quick Start

Just want the AI skills?

Add 77 AI skills to your existing setup — powered by agent-toolkit:

# Option A: one-shot via uvx (V launcher wheel, no install required)
uvx --from 'agent-toolkit-cli>=1.11.0' agent-toolkit install

# Option B: Homebrew (macOS / Linuxbrew)
brew tap ulises-jeremias/homebrew-tap && brew install agent-toolkit && agent-toolkit install

# Option C: Arch Linux via AUR (native V binary)
yay -S agent-toolkit-bin && agent-toolkit install

# Option D: uv tool (V launcher wheel)
uv tool install --force 'agent-toolkit-cli>=1.11.0' && agent-toolkit install

# Option E: install-skills.sh (agentic-workstation wrapper)
curl -fsSL https://github.com/ulises-jeremias/agentic-workstation/releases/latest/download/install-skills.sh | bash

Works instantly with Claude Code, Muse Code, opencode, Cursor, GitHub Copilot, and Gemini CLI. Learn more →

Full workstation (dotfiles + skills + everything)

chezmoi init --apply ulises-jeremias/agentic-workstation

Integrations

Seamless skill packs for the tools you use every day:

Architecture

Details and Mermaid diagrams: docs/ARCHITECTURE.md.

Agent Toolkit Swarms — tmux + Herdr

Workstation installs tools, Toolkit owns orchestration. agentic-workstation provisions the machine-level swarm dependencies (tmux + Herdr + OpenCode integration); all swarm orchestration lives in agent-toolkit.

• tmux — terminal multiplexer installed via your system package manager (apt/brew/pacman/dnf). Verified: tmux -V. Workstation uses an isolated socket agent-toolkit-swarm-<run-id> and never overwrites ~/.tmux.conf.
• Herdr — terminal-native app for orchestrating agents. Installed idempotently via brew → mise → curl -fsSL https://herdr.dev/install.sh | sh fallback. Check: herdr --version. Skipped in CI unless SWARM_FORCE_INSTALL=1.
• OpenCode Herdr integration — herdr integration install opencode (idempotent). Creates ~/.config/opencode if missing, safe and credential-free. Verify: herdr integration list --json. Update outdated integrations with the same command.

Verify swarm provisioning:

dots-doctor                 # includes tmux, herdr, and swarm checks
dots-doctor --json | jq
agent-toolkit swarm doctor  # toolkit-level swarm health check

Run a swarm (Toolkit owns orchestration):

herdr                                          # start Herdr app
herdr integration install opencode             # one-time OpenCode integration
agent-toolkit swarm doctor                     # validate swarm prerequisites
agent-toolkit swarm start --recipe pair --ui herdr --runner opencode "Implement feature X"
agent-toolkit swarm start --recipe pair --ui tmux --runner opencode "Implement feature X"
# See agent-toolkit docs: agent-toolkit swarm --help

Profiles technical, non-technical, ai, and data enable the swarm group (install_group_swarm) by default; opt-out via custom questionnaire. See docs/SWARM_SETUP.md, docs/PLATFORM_SUPPORT.md, and docs/AGENT_TOOLKIT.md.

📂 Repository Map

agentic-workstation/
├── home/                    # Chezmoi source state → your $HOME
├── docs/                    # Architecture, ADRs, maintainer guides
├── scripts/                 # Validation, install, and CI helpers
├── static/                  # Banner and media assets
├── .github/workflows/       # 12 CI workflows
├── AGENTS.md                # AI agent guidelines
├── CHANGELOG.md             # Release history
├── CONTRIBUTING.md          # How to contribute
├── SECURITY.md              # Security policy
├── install.sh               # Bootstrap installer (Unix)
├── install.ps1              # Bootstrap installer (Windows)
└── .chezmoiroot → home/     # Chezmoi source root

📋 Architecture Decisions

Key decisions are recorded as ADRs — immutable once accepted, superseded by new ADRs when revisited.

Personal DX Stack

Together, these three projects form my personal workspace: a polished Developer Experience / UX system that optimizes setup, context switching, AI-assisted delivery, and daily workflow automation.

🛠️ Development Checks

bash scripts/check-markdown-tables.sh
bash scripts/check-shell-syntax.sh
bash scripts/validate-repo-structure.sh
git diff --check

Contributing: See CONTRIBUTING.md for PR guidelines, commit conventions, and branch naming.

🔒 Security

Never commit credentials, tokens, or private keys. Use the wiki credentials flow for local secrets.

⭐ Star this repo if you use it — it helps others discover it.

Report a bug · Request a feature

Built with ❤️ for AI-assisted software delivery

👥 Contributors

Made with contributors-img.