{"slug": "husk-a-desktop-workspace-for-terminal-ai-agents", "title": "Husk – a desktop workspace for terminal AI agents", "summary": "Husk, a desktop workspace for terminal AI agents, wraps tools like Claude, Copilot, Codex, and Aider in an Electron window with a real PTY, drag-drop file context, voice output, session resume, and a dashboard. The open-source project, available via a one-line install script for Linux, macOS, and Windows, aims to make CLI-based AI agents more approachable by adding a graphical interface while preserving the original terminal functionality.", "body_md": "Husk wraps `claude`\n\n, `copilot`\n\n, `codex`\n\n, `aider`\n\n, or any other terminal-based AI agent in a clean Electron window with a real PTY, drag-drop file context, voice output, session resume, and a one-glance dashboard. The reasoning, thinking format, and Algorithm phase machine are bundled in. Clone, install, run.\n\n## husk-overview.mp4\n\nCLI agents are powerful and free. But they live in a black-on-black terminal that newcomers find intimidating, lose track of work in, and never discover the features of. Husk keeps the agent exactly as it is and adds the surface that makes it usable: file drops, persistent sessions, a status panel, a skills view, voice readback, and an installer that takes care of itself. If you can already use the terminal, Husk does not get in your way. If you cannot, Husk makes the same agent approachable.\n\n*Chat in a real PTY with full TUI fidelity, drag-drop context, and a live status panel.*\n\n*Curate the agent personas active for the next session. Start a multi-step automation from a ready-made topology, or build your own in the graph editor.*\n\n*Run a workflow and watch it play out on the graph: each step lights up as it runs, the edge fires to the next, and every node keeps its own terminal.*\n\n*Pin folders as Projects so the agent always starts in the right cwd. Save reusable prompts and fire them with one click.*\n\n*Browse skills by source, switch them on per skill or a whole folder at once, and see what was added recently. MCP servers with live connection state and a curated catalog.*\n\n*Install any MCP server: pick stdio or HTTP/SSE, fill the form, or paste the canonical JSON shape and Husk fills it for you.***One line, any OS.** Checksums verified, no `git clone`\n\n, no Node.\n\n```\n# Linux and macOS\ncurl -fsSL https://dorshaer.github.io/Husk/install.sh | bash\n# Windows\nirm https://dorshaer.github.io/Husk/install.ps1 | iex\n```\n\nOn Debian/Ubuntu it wires up the signed apt repo and installs Husk, so `apt upgrade`\n\nkeeps it current. On Fedora it installs the `.rpm`\n\n, on other Linux the AppImage, on macOS the `.dmg`\n\n, on Windows the installer.\n\nFull per-platform install page: ** dorshaer.github.io/Husk**.\n\n```\n# Debian / Ubuntu: add the signed apt repo once, then `apt upgrade` keeps Husk current\ncurl -fsSL https://dorshaer.github.io/Husk/husk.gpg | sudo tee /usr/share/keyrings/husk.gpg > /dev/null\necho \"deb [signed-by=/usr/share/keyrings/husk.gpg] https://dorshaer.github.io/Husk/apt stable main\" | sudo tee /etc/apt/sources.list.d/husk.list\nsudo apt update && sudo apt install husk\n\n# Or install a downloaded .deb by hand\nsudo dpkg -i husk-v*-linux-amd64.deb || sudo apt -f install\n\n# Or run the portable AppImage (no root; needs libfuse2)\nchmod +x husk-v*-linux-x86_64.AppImage && ./husk-v*-linux-x86_64.AppImage\n\n# Or build from source\ngit clone https://github.com/DorShaer/Husk.git && cd Husk && ./installer/install.sh\n```\n\nOnly x86_64 Linux builds are published today. There is no arm64 Linux build yet, and the binaries are glibc-linked, so musl distros (Alpine) are not supported.\n\n```\n# One line (Apple Silicon or Intel, auto-detected)\ncurl -fsSL https://dorshaer.github.io/Husk/install.sh | bash\n\n# Or download the .dmg from the releases page and drag Husk to Applications.\n# Husk is not code-signed yet, so clear the quarantine flag on first launch:\nxattr -dr com.apple.quarantine /Applications/Husk.app\n# One line: downloads the installer, verifies its checksum, runs it\nirm https://dorshaer.github.io/Husk/install.ps1 | iex\n```\n\nOr download `husk-v<version>-win-x64.exe`\n\nfrom the [latest release](https://github.com/DorShaer/Husk/releases/latest) and run it. The build is not code-signed yet, so SmartScreen shows a warning; choose **More info > Run anyway**.\n\nPrefer to grab an installer by hand? Pull the latest for your OS from the [releases page](https://github.com/DorShaer/Husk/releases):\n\n| OS | Download |\n|---|---|\n| Linux | `husk-v<version>-linux-x86_64.AppImage` (double-click), `-amd64.deb` , or `-x86_64.rpm` |\n| macOS | `husk-v<version>-mac-arm64.dmg` (Apple Silicon) or `husk-v<version>-mac-x64.dmg` (Intel); drag to Applications |\n| Windows | `husk-v<version>-win-x64.exe` (NSIS installer) |\n\nNo Node, no npm, no `git clone`\n\n. Husk bundles its own Electron runtime and copies the agent reasoning layer into `~/.claude/`\n\non first launch.\n\nmacOS first launch (unsigned builds).The .dmg ships unsigned today. Drag Husk to Applications, try to open it, clickCancelon the Gatekeeper prompt, then openSystem Settings → Privacy & Security, scroll down, and clickOpen Anyway. A second prompt confirms and Husk launches normally from then on. Faster path if you live in the terminal:`xattr -dr com.apple.quarantine /Applications/Husk.app`\n\n. Apple Developer ID signing is on the roadmap.\n\nEvery release ships a `SHA256SUMS`\n\nfile plus Sigstore build-provenance attestations bound to the workflow run that produced the artifacts.\n\n```\n# Checksum the file you downloaded\nsha256sum -c SHA256SUMS\n\n# Verify provenance (requires gh CLI 2.49+)\ngh attestation verify husk-v<version>-mac-arm64.dmg --repo DorShaer/Husk\n```\n\nFor contributors and tinkerers:\n\n```\ngit clone https://github.com/DorShaer/Husk.git husk\ncd husk\n./installer/install.sh\n```\n\n`install.sh`\n\nruns `npm install`\n\n, rebuilds `node-pty`\n\nfor Electron's Node ABI, registers Husk with your OS (`.desktop`\n\non Linux, `.app`\n\nbundle in `~/Applications`\n\non macOS), and bootstraps LifeOS into `~/.claude/`\n\n.\n\nFor pure dev mode without system registration:\n\n```\n./scripts/run.sh\n```\n\nThe full walkthrough (prerequisites, building your own `.deb`\n\n/`.dmg`\n\n/`.exe`\n\n, troubleshooting) is in [docs/build-from-source.md](/DorShaer/Husk/blob/main/docs/build-from-source.md).\n\n```\n./installer/uninstall.sh             # remove launcher, icon, config, voice models\n./installer/uninstall.sh --keep-data # preserve config and Piper voices\n```\n\nThe source checkout and `node_modules/`\n\nare protected; if the checkout is inside\na cleanup path such as `~/.local/share/husk`\n\n, the uninstaller skips that path.\n\n- Launch Husk from your applications menu, or run\n`husk`\n\nfrom a terminal after installing. - On first run, Husk asks for the agent's name (default: Husk) and the agent command (default:\n`claude`\n\n). Both are saved to`~/.config/husk/config.json`\n\nand can be edited later in Preferences. - Press the Launch button and start chatting. The agent runs in a real PTY, so everything you would normally do in the terminal works: tool calls, slash commands, stdin, ctrl-c, scrollback, keyboard interrupts, the lot.\n- Drag files onto the window to share them with the agent. Use the topbar\n`+`\n\nbutton as a fallback file picker. - Switch pages with the rail or\n`Alt+1..6`\n\n. Open the command palette with`Cmd/Ctrl+K`\n\n. - If a chat starts agents that keep working on their own, the topbar says how many are running and how many are waiting on you. Click it or press\n`Alt+A`\n\nto pick one and continue its conversation.\n\n**Chat**: the PTY surface. Drag-drop files, status panel on the right.** Agents**: pick which agent personas activate for the next session. Multiple can be active at once; import from any local CLI's agent dir, or install an agent pack from a local repo folder or a repo URL (e.g.`https://github.com/dev/agent-repo`\n\n).**Workflows**: a visual graph editor for chained steps with conditional branching and AI-decided routing.** Projects**: switch the agent cwd between known project directories (so Claude's \"remember this folder\" trust prompts work).** Autopilot**: hand the agent a goal and walk away. Solo runs one agent; Team splits the goal across collaborating parallel runs. Each run executes in its own git worktree with a dedicated PTY, an independent time/token/dollar budget, a hash-chained audit log, and an optional pre-run snapshot for one-click revert. A swarm bar shows every active run.**Prompts**: local-only prompt library; one click sends a saved prompt into the agent.** Skills**: toggle the skills bundled with Husk plus any skills you keep in`~/.claude/skills/`\n\n.**MCP**: install / toggle / health-check Model Context Protocol servers.** Plugins**: browse and manage Husk plugins.** Files**: drag-drop file context, with a tree view of your working directory.** Sessions**: resume any prior agent session from its JSONL log. Agents a chat started are grouped under that chat rather than listed beside it.\n\nPreferences (agent command, name, theme, accent, voice, recap, sidebar defaults) open as a modal from the rail or `Alt+6`\n\n, not as a page.\n\n```\nhusk/\n├── src/                       Application source\n│   ├── main.js                Electron main process: IPC, agent control\n│   ├── preload.js             contextBridge window.husk surface\n│   ├── lib/                   Pure helpers (unit-tested)\n│   │   ├── shell-quote.js     POSIX argv serializer\n│   │   ├── path-confine.js    resolveInside / isInside under a root\n│   │   ├── pty-spawn.js       Per-platform pty.spawn argv assembly\n│   │   ├── user-path.js       Inherit shell PATH on GUI launch\n│   │   ├── agent-md.js        Agent markdown frontmatter parser\n│   │   ├── workflow-graph.js  Sanitize, migrate, traverse, route\n│   │   ├── mcp/               Per-agent MCP adapters\n│   │   ├── autonomy/          Autopilot budget, audit log, snapshot, supervisor\n│   │   └── ...                ~28 modules total; see docs/architecture.md\n│   └── renderer/              UI (single-page Electron view)\n│       ├── index.html\n│       ├── app.js\n│       ├── styles.css\n│       ├── assets/\n│       └── vendor/            Bundled xterm.js + addons\n├── installer/                 OS install assets + verify helpers\n│   └── lib/                   Download-and-verify (verify.sh, verify.ps1)\n├── libs/\n│   └── lifeos/                Bundled LifeOS framework, third-party\n├── test/                      Unit tests (node:test) + Electron smoke\n│   ├── unit/                  node:test unit suite (500+ tests)\n│   └── e2e/                   Playwright smoke (real Electron boot)\n├── installer/                  source installers, packaging assets, landing page\n├── package.json\n├── README.md\n└── LICENSE\n+--------------------+       IPC       +-----------------------+\n|   Electron main    |  <----------->  |       Renderer        |\n|   src/main.js      |                 |    src/renderer/      |\n|                    |                 |                       |\n|  - node-pty        |   PTY stream    |  - chat surface       |\n|  - per-platform    |  ------------>  |  - agents + workflows |\n|    spawn (see lib) |                 |  - skills + prompts   |\n|  - all IPC handlers|                 |  - sessions + files   |\n|  - shell PATH      |                 |  - MCP + preferences  |\n|    augmentation    |                 |  - status panel       |\n+--------------------+                 +-----------------------+\n         |                                        |\n         v                                        v\n   ~/.claude/*                             contextBridge\n   (bootstrapped from                      window.husk API\n    libs/pai on first                      (src/preload.js)\n    install)\n```\n\n`src/main.js`\n\nis the Electron main process. It assembles the PTY spawn per platform (see`src/lib/pty-spawn.js`\n\n): direct`pty.spawn(exe, argv)`\n\non macOS,`/usr/bin/script -q -c <argv>`\n\non Linux so`claude --resume`\n\ngets its TIOCSCTTY setup, and PATH+PATHEXT resolution before`pty.spawn`\n\non Windows. It exposes IPC handlers for skills, sessions, voice, MCP servers, file drops, workflows, agents, projects, and live stats.`src/lib/`\n\nholds the pure helpers: shell-quote, path-confine, pty-spawn, user-path, agent-md, workflow-graph, the`mcp/`\n\nper-agent adapters, the`autonomy/`\n\nAutopilot safety modules, and about twenty more (see`docs/architecture.md`\n\n). Each is small, with no Electron / fs / spawn coupling, and unit-tested. New IPC handler logic should land here.`src/preload.js`\n\nexposes a narrow`window.husk`\n\nAPI to the renderer through`contextBridge`\n\n. The renderer never gets Node access.`src/renderer/`\n\nis the renderer: a single-page Electron view with rail navigation, an embedded xterm, a status panel, and the Chat / Agents / Workflows / Autopilot / Projects / Prompts / Skills / MCP / Plugins / Files / Sessions surfaces plus the Preferences modal.`libs/lifeos/`\n\nis the bundled LifeOS framework, copied into`~/.claude/`\n\non first install. Contains the system prompt, Algorithm phase machine, agents, commands, hooks, the identity scaffold, and the curated skills set. An install that already has the older`~/.claude/PAI/`\n\nlayout is left alone rather than given a second framework beside it.`installer/`\n\nholds OS install assets and the SHA-256 download verifier (`verify.sh`\n\n,`verify.ps1`\n\n).`installer/`\n\nholds the source installers (`install.sh`\n\n,`install.ps1`\n\n,`uninstall.sh`\n\n) alongside the packaging assets they use.`scripts/`\n\nholds the published one-line installers and the dev launcher (`run.sh`\n\n). The repo root stays free of loose scripts.\n\n```\n./scripts/update-vendor.sh            # framework + dependencies, every gate\n./scripts/update-vendor.sh --fast     # skip the package build and the e2e run\n./scripts/update-vendor.sh --commit   # commit once everything passes\n```\n\nRefreshes `libs/lifeos/`\n\nfrom the latest upstream release and the npm tree\nwithin the ranges `package.json`\n\nalready allows, then refuses to leave anything\nstaged unless it passes:\n\n**Privacy.** The whole vendored tree, plus every line the run added elsewhere, is searched for identifiers belonging to the machine running it: home directory, username, hostname, git name and email. Those are read from the environment at run time and never written to a file, because hard-coding them is the thing being guarded against. The framework is always taken from the published release tarball, never from a local`~/.claude`\n\n, which is where a maintainer's own notes and answered templates live.**Secrets and CVEs.** gitleaks over full history and trivy over the manifests, both pinned to the versions CI uses so a local pass means a CI pass.**Package size.** Builds the`.deb`\n\nand fails below the 100 MiB ceiling that the apt channel silently breaks at.**Tests.** Unit always, end-to-end unless`--fast`\n\n.\n\nA failing gate restores the working tree, so a bad run leaves nothing behind.\nLocal corrections to vendored files (a dependency range moved off an\nunpatchable version, say) live in `VENDOR_FIXUPS`\n\ninside the script and are\nre-applied after each refresh, since re-vendoring would otherwise revert them\nsilently.\n\n```\nnpm test         # node:test unit suite (500+ tests), well under a second\nnpm run test:e2e # Playwright smoke that boots real Electron\nnpm run test:all # both\n```\n\nCI runs both jobs on every push to `main`\n\n, `development`\n\n, and `dev/**`\n\n, and on every pull request to `main`\n\nor `development`\n\n.\n\n`main`\n\ncarries released code. Tags`v*`\n\nare cut from here, the release workflow builds installers, and SHA256SUMS plus Sigstore build-provenance attestations ship alongside them.`development`\n\nis the integration branch where active work lands. Feature branches use`dev/<short-name>`\n\nand open pull requests against`development`\n\n.- Releases merge\n`development`\n\ninto`main`\n\n, then a`v<x>.<y>.<z>`\n\ntag triggers the release pipeline. - CI (lint, security scans, unit tests, Electron smoke) runs on every push and pull request to either long-lived branch.\n\nAll settings live in `~/.config/husk/config.json`\n\nand are editable from the Preferences page:\n\n**Agent command**(`claude`\n\n,`copilot`\n\n,`codex`\n\n,`aider`\n\n, or any binary on`$PATH`\n\n) and**agent name****Active agent profiles**: one or more agent personas applied to the next session** Active project**: drives the agent's working directory so per-folder trust prompts work** Theme**(10 themes: Midnight default, Dark, Tokyo Night, Catppuccin, Rose Pine, Gruvbox, Nord, Dracula, Light, Sepia) and** accent color**(orange / cyan / indigo / emerald / rose)** Voice**(enable, voice model, speaking rate)** Show recap line**(when off, suppresses end-of-response summaries)** Sidebar default state**,** status panel collapsed**,** file tree root**,** show hidden files**\n\nHusk runs entirely on your machine. No telemetry. No analytics. The only network calls are made by the agent CLI itself when it talks to its model provider, and by the optional voice installer when it downloads Piper and a voice model from their public release.\n\nMIT.\n\nHusk's reasoning, thinking format, and Algorithm phase machine come from [LifeOS](https://github.com/danielmiessler/LifeOS) (formerly PAI) and Telos by **Daniel Miessler**. If you find Husk useful go show him some love.\n\nThe terminal embedding uses [ xterm.js](https://github.com/xtermjs/xterm.js) plus\n\n[. On Linux the PTY is established through](https://github.com/microsoft/node-pty)\n\n`node-pty`\n\n`script(1)`\n\nso `claude --resume`\n\ngets its controlling terminal. Voice is via [Piper TTS](https://github.com/rhasspy/piper). The workflow editor uses\n\n[Drawflow](https://github.com/jerosoler/Drawflow).", "url": "https://wpnews.pro/news/husk-a-desktop-workspace-for-terminal-ai-agents", "canonical_source": "https://github.com/DorShaer/Husk", "published_at": "2026-07-29 21:28:55+00:00", "updated_at": "2026-07-29 21:52:41.098116+00:00", "lang": "en", "topics": ["ai-tools", "developer-tools", "artificial-intelligence"], "entities": ["Husk", "Claude", "Copilot", "Codex", "Aider", "Electron", "DorShaer"], "alternates": {"html": "https://wpnews.pro/news/husk-a-desktop-workspace-for-terminal-ai-agents", "markdown": "https://wpnews.pro/news/husk-a-desktop-workspace-for-terminal-ai-agents.md", "text": "https://wpnews.pro/news/husk-a-desktop-workspace-for-terminal-ai-agents.txt", "jsonld": "https://wpnews.pro/news/husk-a-desktop-workspace-for-terminal-ai-agents.jsonld"}}