ACE
Terminal assistant for developers: a project registry with instant navigation, a guarded Git save flow, scheduling, backups, a tmux dashboard and a Textual TUI. Installable with pipx, tested on Python 3.10 to 3.14.
Overview
A.C.E. (Automated Command Environment) is a developer assistant that lives in the terminal. It keeps a registry of your projects, jumps between them, saves work through a guarded Git flow, runs scheduled commands, backs projects up and shows it all on a tmux dashboard or a Textual TUI.
- Commands
- 10 top-level
- Python tested
- 3.10 – 3.14
- Runtime deps
- 5
- Install
- pipx, tagged releases
It is a tool I use every day, so the design goal was low friction: one command per habit, fast startup, and nothing that can quietly damage a repository.
Architecture
A thin command router in front of one module per feature, with a small persistent store.
ace <command>
└─ src/main.py argparse tree + dispatch (lazy imports)
├─ src/core/ config, shared context, memory, service lifecycle
├─ src/features/ project_manager · vanguard · scheduler · backup
│ dashboard · news_hub · scaffolder · voice (experimental)
├─ src/tui/ Textual app: screens, widgets, services, tcss
└─ src/shell.py acego function + rc-file installer
data/ project registry + schedule store (JSON, git-ignored)
.env GitHub credentials (git-ignored)- Lazy imports · Each handler imports its feature module only when that command runs, so ace --help and ace --version stay instant even though textual and feedparser are installed.
- Handler guard · Every subcommand must set a handler. If one does not, the router stops with "no handler wired for '<command>'" instead of exiting silently.
- Persistence · Plain JSON for the project registry and the schedule. Easy to read, diff and repair by hand, which matters more than speed for a few dozen records.
Vanguard (Git)
The part that touches your history, so it is the most defensive part.
| Command | Behaviour |
|---|---|
| ace save <nickname> | Refuses to run on main or master. Shows git status, asks to proceed, asks for a message (empty aborts), then stages, commits and pushes to the current feature branch |
| ace overview | Runs git status and the last commit for every registered project in parallel on a thread pool, then prints one summary |
Each step reports its own failure, a clean working tree short-circuits with "nothing to save", and a missing path or a non-repository is a line in the overview rather than a crash that hides the other projects.
Automation
Scheduling, backups, news and a ready-made workspace.
- Scheduler · ace schedule add/list/remove stores jobs with auto-incrementing ids in JSON; ace scheduler start runs a watcher that executes each job as a subprocess of the ace entry point.
- Backups · ace backup [nickname] writes a gzipped tarball per project into a dated folder, named with the short commit hash so you know which state it is.
- News · ace news reads developer feeds (Hacker News, TechCrunch) with feedparser and prints titles with links.
- tmux dashboard · ace dashboard start builds a tiled session: news refreshed every 5 minutes in one pane, the Git overview every minute in another, and a workspace window. If the session exists, it attaches instead of rebuilding.
The TUI
A Textual interface over the same features, for when you would rather browse than type.
- Layout · A keyboard-driven tiling screen: focusable tile windows with titles, in the spirit of i3.
- Launcher · Press / for a floating launcher menu (chat assistant, project manager, Vanguard, news reader) and Esc to close it. Ctrl+H and Ctrl+L move focus between panels.
- Widgets · Project and Vanguard widgets reuse the same feature modules as the CLI, so there is one implementation of each behaviour.
- Styling · A single .tcss stylesheet, so the look is data, not code.
Install & release
Installable like any real tool, and verified on every Python it claims to support.
- Packaging · A pyproject.toml with an ace entry point. pipx install git+…@v0.2.0 for a release, or pipx install --editable . for development.
- CI · A matrix on Python 3.10, 3.11, 3.12, 3.13 and 3.14 installs the package and smoke-tests ace --version, --help, project --help and shell-init.
- Release · Pushing a v* tag builds the package and publishes a GitHub Release, after checking that the tag equals the version in pyproject.toml.
- Config · Secrets in .env (git-ignored), non-secret settings in config/settings.toml.
Status & next
Honest about what is finished.
- Solid · Project registry, acego, guarded save, parallel overview, backups, tmux dashboard, CI and releases.
- Placeholder · The scheduler currently runs every job each minute instead of parsing the time rule; a real rule parser is the next fix. The Python scaffold template is a stub.
- Early · The TUI launcher lists a chat assistant whose service modules are still empty, and voice handling is experimental and not installed by default.
Deep dive
Bugs that cost real time, with what the symptom looked like, the actual cause, and the fix.
Symptom
An executable called acego could print a path but never move your shell there.
Diagnosis
A child process cannot change its parent's working directory. Anything that must cd has to run inside the shell itself.
Fix
acego is a shell function that asks ace project go for the path and cds. Because shell functions come from startup files, ace shell-init --install writes it for you.