Skip to content
BranchesTags

Repository files navigation

agentic-dev-setup

Shareable Herdr + worktrunk dev layout for agentic coding workflows. Works on Omarchy, Ubuntu/Debian, and macOS.

Successor to agentic-tmux-setup — same sticky-agent layout, powered by Herdr instead of tmux.

image

Quick install

curl -fsSL https://setup.simoncrypta.dev/install.sh | bash

Non-interactive (skip agent prompt):

curl -fsSL https://setup.simoncrypta.dev/install.sh | bash -s -- --yes

From a local clone:

cd /path/to/agentic-dev-setup
./install.sh

What you get

  • Herdr layout: sticky agent pane (left) + tabs for review (tuicr), explorer (nvim), terminal
  • Dev layout plugin: agentic-dev.dev-layout (pinned from simoncrypta/herdr-dev-layout)
  • Worktrunk plugin: in-Herdr git worktree pickers (prefix+shift+g/c/r)
  • Shell commands: dev, wtc, wts, wtd, d, t
  • worktrunk hooks: auto-create/close Herdr workspaces on worktree start/remove
  • Config: ~/.config/agentic-dev/config.toml (agent command + editor)
  • Omarchy/Linux: fcitx5 hint hotkeys cleared (Ctrl+Alt+H/J); optional Hyprland binding patch
  • Ubuntu/Debian: apt installs for common deps; tuicr/herdr/worktrunk via GitHub when needed

Layout

One Herdr workspace per worktree. The agent pane stays on the left (~50%); tool tabs are on the right. Switching tabs moves the agent pane with you — it is not its own tab.

┌──────────────────────────────────────────────────────────────────┐
│  workspace tabs   review   explorer   terminal      PREFIX  #h │
├─────────────────────────┬────────────────────────────────────────┤
│                         │                                        │
│   agent                 │   active tool tab                      │
│   (agent / codex /      │                                        │
│    opencode / claude)   │   review    → tuicr                    │
│                         │   explorer  → nvim (neo-tree)          │
│   sticky left pane      │   terminal  → shell                    │
│                         │                                        │
│   prefix+1              │   prefix+2/3/4  or  Alt+1/2/3          │
└─────────────────────────┴────────────────────────────────────────┘

Prefix is Ctrl-Space (same as Omarchy tmux). prefix+d applies this layout in the current workspace.

First-run prompt

On install you'll pick the agent pane command:

  1. agent
  2. codex
  3. opencode
  4. claude
  5. custom

Saved to ~/.config/agentic-dev/config.toml. Change later with agentic-dev reconfigure.

Shell commands

Command Description
dev Dev layout for current directory
wtc [branch] Create worktree + new Herdr workspace
wts [branch] Switch to existing worktree (fzf picker)
wtd [branch] Remove worktree + close Herdr workspace
d Apply layout in current Herdr workspace
t Launch herdr

Herdr keys

Prefix is Ctrl-Space, matching Omarchy tmux. Bindings live in config/herdr/config.toml.

Roles

Layer Owns Examples
Native Herdr Panes, tabs, workspaces splits, close workspace, detach
Dev-layout plugin Sticky agent layout apply layout, review/explorer/terminal
herdr-worktrunk plugin Git worktree pickers open / open-current / remove

prefix+shift+d is not bound to worktrunk remove — that key is Herdr’s native close-workspace by default, so remove lives on prefix+shift+r instead. Workspace close is on prefix+shift+k (Omarchy’s kill-session analog).

Dev layout

Key Action
prefix+d Apply / ensure sticky-agent layout
prefix+1 Focus agent pane (recreates if crashed)
prefix+2 Review tab (tuicr)
prefix+3 Explorer tab (nvim)
prefix+4 Terminal tab
Alt+1 / Alt+2 / Alt+3 Same tabs in a dev workspace; otherwise focus tab 1/2/3

Prefix 1–4 no-op outside a valid dev-layout workspace (they never create a layout). Only prefix+d / create / apply create one.

Tabs (≈ Omarchy windows)

Key Action
prefix+c New tab
prefix+k Close tab
prefix+shift+t Rename tab
prefix+n / Alt+Right Next tab
prefix+p / Alt+Left Previous tab

Workspaces (≈ Omarchy sessions)

Key Action
Alt+Up / Alt+Down Previous / next workspace
prefix+w Workspace picker
prefix+shift+n New workspace
prefix+shift+w Rename workspace
prefix+shift+k Close workspace
prefix+shift+q Detach

Panes

Key Action
prefix+h Split below
prefix+v Split beside
prefix+x Close pane
prefix+z Zoom pane
Ctrl+Alt+H/J/K/L Focus left / down / up / right

Pane focus uses vim keys instead of Omarchy’s Ctrl+Alt+Arrows so it stays clear of desktop/arrow chords; on Omarchy/Linux the installer also clears fcitx5’s Ctrl+Alt+H/J hint hotkeys.

Git worktrees (herdr-worktrunk)

Key Action
prefix+shift+g Open / create worktree from default branch
prefix+shift+c Open / create worktree from current branch
prefix+shift+r Remove worktree

Shell equivalents still work outside Herdr: wtc, wts, wtd.

General

Key Action
prefix+q Reload Herdr config

Tab switching works even when the agent pane is missing — the agent is recreated lazily on the next tab switch or prefix+1.

Post-install CLI

agentic-dev help         # full reference
agentic-dev doctor       # check deps + integration
agentic-dev update       # re-sync configs
agentic-dev reconfigure  # change agent command
agentic-dev dry-run      # preview changes
agentic-dev uninstall    # remove integration

Omarchy / Linux notes

Ubuntu / Debian

Dependencies install via apt when available:

sudo apt-get install -y git fzf jq neovim lazygit curl

Tools not in apt are fetched automatically:

  • herdr — herdr.dev/install.sh
  • worktrunk (wt) — GitHub release binary to ~/.local/bin
  • tuicr — GitHub release binary to ~/.local/bin

Homebrew (Linuxbrew) is used when present and takes priority over apt.

On Ubuntu with Hyprland, the installer can optionally add SUPER+ALT+RETURN → herdr in ~/.config/hypr/bindings.conf. If you use fcitx5 (common on CJK setups), the Ctrl+Alt+H/J hint hotkey fix applies the same way as on Omarchy.

fcitx5 Ctrl+Alt+H conflict

Omarchy runs fcitx5 for emoji and compose. By default fcitx5 binds Ctrl+Alt+H/J to spell-hint toggles, which conflicts with Herdr pane focus. This installer clears those hotkeys in ~/.config/fcitx5/conf/keyboard.conf.

See Omarchy discussion #1578.

Hyprland launcher

On Omarchy or any system with ~/.config/hypr/bindings.conf, the installer can patch a key binding to launch herdr on SUPER+ALT+RETURN (replacing tmux if present). You'll be prompted during install.

Omarchy uses uwsm-app and omarchy-cmd-terminal-cwd; other Hyprland setups get a generic xdg-terminal-exec herdr binding.

Dependencies

Installed only if missing (Homebrew, apt, pacman, or upstream installers):

  • herdr (brew, or curl -fsSL https://herdr.dev/install.sh | sh)
  • git, worktrunk (wt), fzf, jq, tuicr, neovim, lazygit

Files installed

~/.config/agentic-dev/config.toml
~/.config/agentic-dev/shell/agentic-dev.{sh,zsh,inc.sh}
~/.config/herdr/config.toml
~/.config/herdr/plugins/dev-layout/
~/.config/worktrunk/herdr-layout.sh
~/.config/worktrunk/config.toml   (only if not already present)
~/.config/fcitx5/conf/keyboard.conf   (Linux, when fcitx5/Omarchy)
~/.local/bin/agentic-dev
~/.local/share/agentic-dev/lib/  (for CLI)

Shell rc gets a fenced marker block in ~/.bashrc and/or ~/.zshrc.

Plugin only

Use this if you already have Herdr configured and only want the dev layout plugin (agentic-dev.dev-layout) — sticky agent pane + review / explorer / terminal tabs.

Requires: Herdr 0.7+, jq, and the review-tab tools you use (tuicr, nvim, etc.).

Trust and security

Herdr plugins are ordinary code that runs as your user and can call the full Herdr CLI. See Herdr: Trust and security.

Before installing:

  1. Skim plugins/dev-layout/herdr-plugin.toml and plugins/dev-layout/dev-layout.sh.
  2. Prefer interactive install (no --yes) the first time — Herdr shows a preview of the source and commands.
  3. Pin a release when you want a fixed revision:
herdr plugin install simoncrypta/agentic-dev-setup/plugins/dev-layout --ref v0.1.1

Use --yes only for sources you already trust. The full curl | bash installer copies and links the plugin locally — equivalent to trusting this repository.

Install the plugin

From GitHub (review the preview, then confirm):

herdr plugin install simoncrypta/agentic-dev-setup/plugins/dev-layout

Pinned to a release:

herdr plugin install simoncrypta/agentic-dev-setup/plugins/dev-layout --ref v0.1.1

From a local clone (development):

git clone https://github.com/simoncrypta/agentic-dev-setup.git
herdr plugin link ~/path/to/agentic-dev-setup/plugins/dev-layout

Verify:

herdr plugin list
herdr plugin action invoke agentic-dev.dev-layout.create

Wire up keybindings

Add the plugin actions to ~/.config/herdr/config.toml. Minimum bindings:

[[keys.command]]
key = "prefix+d"
type = "plugin_action"
command = "agentic-dev.dev-layout.apply"

[[keys.command]]
key = "prefix+1"
type = "plugin_action"
command = "agentic-dev.dev-layout.focus_agent"

[[keys.command]]
key = "alt+1"
type = "plugin_action"
command = "agentic-dev.dev-layout.select_review"

[[keys.command]]
key = "alt+2"
type = "plugin_action"
command = "agentic-dev.dev-layout.select_explorer"

[[keys.command]]
key = "alt+3"
type = "plugin_action"
command = "agentic-dev.dev-layout.select_terminal"

Or copy the full example from config/herdr/config.toml in this repo (prefix Ctrl-Space, pane focus on Ctrl+Alt+HJKL, etc.).

Reload after editing:

herdr server reload-config

Agent command (optional)

The plugin reads settings from the Herdr plugin config directory first, then falls back to the full-setup path:

  1. $(herdr plugin config-dir agentic-dev.dev-layout)/config.toml — preferred (Herdr convention)
  2. ~/.config/agentic-dev/config.toml — when using the full installer
herdr plugin config-dir agentic-dev.dev-layout
cp plugins/dev-layout/config.toml.example "$(herdr plugin config-dir agentic-dev.dev-layout)/config.toml"
# edit command / editor, then re-run create or apply

Minimal config:

[agent]
command = "agent"

[layout]
editor = "nvim"

Without config, the agent pane defaults to agent and the explorer tab uses $EDITOR or nvim.

Invoke without keybindings

herdr plugin action invoke agentic-dev.dev-layout.create   # create layout in focused workspace
herdr plugin action invoke agentic-dev.dev-layout.apply    # ensure layout exists
herdr plugin action invoke agentic-dev.dev-layout.select_review

The full installer also adds shell commands (dev, wtc, …), worktrunk hooks, and Linux desktop fixes — use Quick install if you want those.

Migrating from agentic-tmux-setup

agentic-tmux uninstall
curl -fsSL https://setup.simoncrypta.dev/install.sh | bash

Cloudflare hosting

Install CDN on Cloudflare Pages (agentic-dev-setup.pages.dev) with custom domain setup.simoncrypta.dev.

URL Behavior
https://setup.simoncrypta.dev/ 301 → GitHub repo (Worker)
https://setup.simoncrypta.dev/install.sh Installer script (Worker → Pages)
https://agentic-dev-setup.pages.dev/ 301 → GitHub repo (public/_redirects)

The custom domain uses a tiny Worker (workers/setup-domain/) with custom_domain = true, which creates the Cloudflare DNS record automatically. It redirects / to GitHub and proxies everything else to the Pages deployment.

Deploy:

npm install
npm run deploy   # Pages assets + setup.simoncrypta.dev Worker

DNS troubleshooting: if a hostname was queried before the record existed, flush local cache (resolvectl flush-caches) and retry. ping setup.simoncrypta.dev should resolve to a Cloudflare anycast IP (e.g. 172.64.80.1).

Manual DNS fallback (Pages-only, requires CLOUDFLARE_API_TOKEN with Zone.DNS Edit):

CLOUDFLARE_API_TOKEN=... bash scripts/ensure-setup-dns.sh

Development

shellcheck install.sh lib/*.sh bin/agentic-dev config/shell/agentic-dev.inc.sh plugins/dev-layout/dev-layout.sh
./install.sh --help
agentic-dev dry-run
npm run deploy   # publish to Cloudflare Pages

License

MIT — see LICENSE.

About

Shareable Herdr + worktrunk dev layout for agentic coding workflows

setup.simoncrypta.dev

Topics

agentic-codingagentic-ideagentic-workflowherdromarchy

Resources

Readme
MIT license
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Contributors

Languages