agentic-workstation

---

agentic-workstation is an AI-first, chezmoi-managed workstation baseline — a thin host that provisions your machine (chezmoi, shell, packages, LLM policy, tmux/Herdr, and Toolkit installation) and delegates all capabilities to agent-toolkit. Workstation installs tools, Toolkit owns orchestration — 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 (verify with agent-toolkit inventory — 106+ skills, agents, loops). Workstation-only runner logic (dev-companion/runner, LLM policy) is retained — see boundary in docs/DEV_COMPANION_LLM.md and docs/ARCHITECTURE.md. See docs/AGENT_TOOLKIT.md.

---

What You Get

🧩 Skills System 106+ reusable skills via agent-toolkit — ClickUp, Figma, GitHub, GitLab, Slack, dbt, Snowflake, Playwright, and more (agent-toolkit inventory) Jira and Confluence are bundled in agent-toolkit and installed with the canonical Toolkit catalog	🤖 AI Agents Pre-configured agents for code review, security audit, TDD, refactoring, planning, architecture, and E2E testing	🔌 MCP Templates Self-configuring MCP provider templates for LLM servers, APIs, and data sources — zero manual setup
🛠️ CLI Helpers agent-toolkit · dots-doctor · dots-skills · dots-mcp · dots-loadenv — agent-toolkit powers skills, loops, MCP, and workspace operations	🔄 Loop Engineering Structured agent loops with cost estimation, telemetry, drift detection, and automated improvement cycles	🎯 Multi-Tool Sync One skill registration across Claude Code, Muse Code, opencode, Cursor, Copilot CLI, Pi, and Windsurf — no duplicates

---

Quick Start

Just want the AI skills?

Add 106+ 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 (legacy wrapper; Pi, Gemini CLI, and Codex require Option A–D)
curl -fsSL https://github.com/ulises-jeremias/agentic-workstation/releases/latest/download/install-skills.sh | bash

Works with Claude Code, Muse Code, OpenCode, Pi, GitHub Copilot, Gemini CLI, Codex, Cursor, and Windsurf. Learn more →

Full workstation (dotfiles + skills + everything)

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

If you want to…	Follow this
Set up your entire machine from scratch	📘 Wiki Quick Start
Add AI skills to an existing setup	📘 Guided AI Install
Choose your profile and answer prompts	📘 Profiles · 📘 Questionnaire
Configure credentials and integrations	📘 Credentials · 📘 Integrations
Use the CLI	📘 CLI Reference

---

Integrations

Seamless skill packs for the tools you use every day:

📋 Jira	📄 Confluence	✅ ClickUp	💬 Slack
Issues, sprints, epics, JQL, time tracking, admin	Pages, spaces, search, permissions, templates, analytics	Tasks, docs, sprints, goals, comments, templates	Channels, messages, canvases, reactions, notifications
🐙 GitHub	🦊 GitLab	🎨 Figma	📊 Linear
PRs, issues, CI, releases, comments, code review	MRs, issues, CI/CD, pipelines, merge requests	Designs, components, variables, code generation, code connect	Issues, projects, cycles, teams, triage, roadmaps
🗄️ dbt	❄️ Snowflake	🎭 Playwright	📓 Jupyter
Parse, compile, test, selective run, CI validation	Read-only SQL validation, warehouse introspection	E2E tests, browser automation, snapshots, traces	Scaffold, run, refactor notebooks — reproducible science

---

Architecture

Layer	Repo	Responsibility
L1	agentic-workstation (thin, this repo)	Machine provisioning + host runner — chezmoi, packages, shell, LLM policy, tmux/Herdr, Toolkit installation, dev-companion/runner (thin, no embedded skills)
L1.5	agent-toolkit	Sole capability distribution — 106+ skills, agents, loops, profiles, MCP, prompts, packs (verify with agent-toolkit inventory)
L3	Project repos / agentic-harness	Overlays — project AGENTS.md, engagement packs, client skills, knowledge, personas

Details and Mermaid diagrams: docs/ARCHITECTURE.md.

Agent Toolkit Swarms — tmux + Herdr

Workstation installs tools, Toolkit owns orchestration. agentic-workstation provisions the host dependencies (chezmoi + packages + shell + LLM policy + tmux + Herdr + OpenCode integration + Toolkit installation); all swarm orchestration, recipes, and isolated tmux sessions (agent-toolkit-swarm-<run-id>) are owned by agent-toolkit. Workstation provisions, Toolkit orchestrates.

• 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.

ADR	Decision	Status
001	Use home/ as chezmoi source state	✅ Accepted
002	Profile-driven tooling model	✅ Accepted
003	AI and MCP baseline in shared local paths	✅ Accepted
004	Skills system with per-tool compatibility matrix	✅ Accepted
005	LLM provider abstraction for dev companion runner	✅ Accepted
006	Multi-tool portability via symlinks and thin adapters	✅ Accepted
007	Agentic harness with three-layer architecture	✅ Accepted
008	Dev companion queue with plan-only default	✅ Accepted
009	Keep name, refresh tagline	⏪ Superseded
010	Rename to agentic-workstation	✅ Accepted

---

Personal DX Stack

dotfiles The personal operating layer: shell, editor, terminal, packages, and day-to-day ergonomics. ulises-jeremias/dotfiles

agentic-workstation The AI-native workstation baseline: skills, agents, MCP templates, CLI helpers, and setup automation. ulises-jeremias/agentic-workstation

agentic-harness The running instance layer: persistent memory, indexed repos, personas, packs, and background loops. ulises-jeremias/agentic-harness

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.

---

👥 Contributors

Made with contributors-img.