That refactor sucked, but amux v0.8 is out now

The past few weeks has been spent rebuilding amux's internals from scratch. The previous architecture was mostly “designed” by Claude and Codex across sixty-plus work items, and by the end it had become clear that the three frontends (CLI, TUI, headless) were each implementing business logic in slightly different ways. A flag added in one place wouldn't always reach the others. Config values were resolved through different code paths depending on which frontend you used. The only way to verify parity was to test all three by hand and compare.

v0.8 fixes this by reorganizing the codebase into a strict four-layer architecture. All business logic now lives in a single shared command layer. The CLI, TUI, and API server are thin presentation layers that translate user input into command calls and render the results. Lower layers can never call upward. It is now much more difficult for an agent to get confused about where it should implement the various concerns of amux when building a new feature.

# install or upgrade
curl -s https://prettysmart.dev/install/amux.sh | sh

What's better for you

Identical behavior across frontends. Every command, flag, and config value is resolved through the same code path regardless of whether you're in the TUI, running a CLI one-liner, or dispatching via the headless API. If it works in one, it works in all three.

Fewer bugs. The old architecture allowed subtle drift between frontends that was hard to test for. The new layering makes that class of bug much less likely.

One little new feature. To test implementing on the new architecture, Skills Overlay was added in v0.8. Your global amux skills (~/.amux/skills/) can now be mounted into any agent container automatically. Enable it with --overlay "skill()", amux config set overlays.skills true, or the AMUX_OVERLAYS env var. amux figures out the right container path for each agent. This allows you to have a personal library of skills you can use without needing to commit them into each project you work on and keep them updated across repos. See the docs for details.

One feature gone. I decided to remove the claws subcommands and features. I want to keep amux small and focused on code agents, and maintaining management of claw agents was time consuming, brittle, and muddled the project’s focus. I still think Nanoclaw is great, though.

Other than that, you should see no breaking changes. Your .amux/config.json, workflows, headless database, and every CLI invocation work exactly as before. amux ready and go. If anything is in fact broken, please file an issue.

This refactor sucked.

Implementing this refactor was harder than expected. The “grand refactor” was specified entirely in advance and executed across eight work items (0066-0073) by code agents driven against the spec. The agents did some good work on individual layers, but re-creating an identical feature set and user experience on top of a completely different architecture turned out to be difficult for them. Even keeping the old source code in the repo for reference still caused the agent to make mistakes in how commands should flow, especially complex ones like exec workflow. It required at least two major mid-layer engine rewrites (the workflow engine and the container runtime) and several follow-up work items (0074, 0077, 0078) to reach full parity.

The core issue is that agents are good at building things in isolation, but not good at preserving the feel of an app across a deep structural change. They can usually match a spec, but re-creating the sum of sixty prior work items' accumulated behaviours — the small UX decisions, the edge cases, the implicit contracts between components — requires a kind of holistic awareness that current models don't have. Getting there took a lot of iteration and a lot of intervention.

That said, I still think it was worth doing. The new architecture makes adding features straightforward, you define a command, register it in the catalogue, implement the per-frontend rendering, and you have a new feature. The skills overlay was built in a single work item with no surprises, which is exactly the kind of experience the refactor was supposed to enable. The new architecture linter helps too.

What's next

Just a note: two other projects I was working on in the background — oasis (a personalized self-hosted agent/app home screen thing) and alog (a “journal for code agents”) — are both going bye-bye. Other people are doing these concepts better, and my heart wasn't really in either of them. I'll be taking a short break from amux development as well. The grand refactor was necessary but frustrating, and I need to step back for a bit. In the meantime I'll be working on a new amux-adjacent project which I'll release soon.

The refactor was a worthy cause. It taught me a lot about agent-assisted software development — both what works well and what still needs to improve. Agents can write solid code in isolation against a clear spec, but software architecture, system-level consistency, and preserving user experience across structural changes are still firmly in the "needs a human" category. For now.

Source and issues at github.com/prettysmartdev/amux. More at prettysmart.dev. Feedback and contributions welcome.