https://github.com/block/cmux-amp
Show your Amp status in cmux
https://github.com/block/cmux-amp
Last synced: 19 days ago
JSON representation
Show your Amp status in cmux
- Host: GitHub
- URL: https://github.com/block/cmux-amp
- Owner: block
- License: apache-2.0
- Created: 2026-03-16T15:16:54.000Z (4 months ago)
- Default Branch: main
- Last Pushed: 2026-05-28T15:30:55.000Z (about 2 months ago)
- Last Synced: 2026-06-06T01:26:31.046Z (about 1 month ago)
- Language: TypeScript
- Size: 40 KB
- Stars: 3
- Watchers: 0
- Forks: 6
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
- Codeowners: CODEOWNERS
- Governance: GOVERNANCE.md
Awesome Lists containing this project
README
# cmux-amp
> [!IMPORTANT]
> Most of the functionality in this plugin has been ported into the core `cmux` app. Please update your version of `cmux`, try it there, and then only install this plugin if that doesn't work.
---
[Amp](https://ampcode.com/) plugin for [cmux](https://www.cmux.dev/) that turns
your cmux tab into a live dashboard for the Amp agent.
Built on the [Amp Plugin API](https://ampcode.com/manual/plugin-api) introduced
with [Amp Neo](https://ampcode.com/news/neo). The plugin API is experimental
and subject to change.
## What you get
- **Live status badge** in the cmux tab switcher — `idle` → `thinking` →
`running: yarn test` / `editing: cmux-status.ts` / `reading: README.md` →
`done` / `error` / `interrupted`. Tool labels include the actual shell
command being run, the file being edited, the search pattern, etc., powered
by the Neo plugin helpers (`shellCommandFromToolCall`,
`filesModifiedByToolCall`).
- **Workspace title tracks the Amp thread ID**, including a chain of any
threads spawned via `handoff`. Manual renames are detected and preserved
across agent restarts.
- **cmux activity log** entries for prompt received, tool errors, spawned
threads, and turn outcomes.
- **`cmux_notify` tool** the agent can call to fire a native macOS
notification when it needs your attention.
- **Command palette actions** under the `cmux:` category:
- `Rename workspace to thread ID`
- `Rename workspace…` (prompts for a new title)
- `Clear Amp status`
- **Macro notification** when an agent turn ends with an error.
- **Session restore** — when cmux relaunches, Amp threads resume in place via
`amp threads continue `. The plugin auto-registers Amp as a custom
vault agent in `~/.config/cmux/cmux.json` and writes a hook-session record
for each thread. Requires cmux nightly or
[≥ 0.64.4 once released](https://github.com/manaflow-ai/cmux/commit/744521d)
(custom vault registry support). Older cmux silently ignores the files.
- Manual fallback: `cmux: Register Amp for cmux session restore` in the
command palette.
## Installation
1. Symlink (or copy) `plugin/cmux-status.ts` into your plugins directory:
- System: `~/.config/amp/plugins/cmux-status.ts`
- Project: `/.amp/plugins/cmux-status.ts`
2. Launch `amp` from inside a cmux workspace.
> Plugins only work when the Amp CLI is installed via the binary install
> method (not `npm install`). See the
> [Amp Plugin API docs](https://ampcode.com/manual/plugin-api) for details.
## Project Resources
| Resource | Description |
| -------------------------------- | ---------------------------- |
| [CODEOWNERS](./CODEOWNERS) | Outlines the project lead(s) |
| [GOVERNANCE.md](./GOVERNANCE.md) | Project governance |
| [LICENSE](./LICENSE) | Apache License, Version 2.0 |