aibo wraps codex to be used in emacs or web but uses a different organization/communication system
Important
Aside from the original design doc and feedback on features/bugs, the code here is purely codex maintained so here be dragons.
Some namings:
| Name | Meaning |
|---|---|
projects |
A short description and a .md file for shared context |
location |
A named local path where a bot works, remote execution over SSH isn't implemented |
m# (manager) |
Default chats that choose an optional project and a location, then delegate to b# when needed |
b# (bot) |
The main conversation, with the project's .md context and the location as its working directory |
| notifications | Instead of a sidebar of all chats, finished chats show up in UNREAD and ACTIVE chats stay at the top |
| keybinds! | M-1 through M-9 open recent bots, C-c b # opens recent managers, M-0 starts a new manager draft |
There are almost no buttons to edit things, it's mainly chat driven such as adding/updating new projects or locations
Dependencies:
codexinPATH(+ authenticated)- Python 3.11+
- Emacs 29+ (+
websocketpackage) - PostgreSQL
- Bun
Inside the aibo dir, to install the python backend:
python -m pip install -e ./pythonAdd to your .emacs or emacs config:
(add-to-list 'load-path "/path/to/aibo/elisp")
(setq aibo:python-command "/path/to/python")
(require 'aibo)Start up with C-M-h to open up aibo
| Keybinding | Action |
|---|---|
C-M-h |
Open the workspace or return home |
M-/ |
Focus input, repeat to toggle the active chat and a new manager draft |
M-0 |
Open a fresh manager draft, create the chat on send |
M-RET |
Send the draft |
RET |
Insert a newline in input, activate a link or selection elsewhere |
C-o |
Switch between chat and input |
C-c C-i |
Attach a clipboard image |
M-m |
Toggle raw/pretty rendering for the message at point |
C-c p s |
Search conversations |
C-c p h |
Show contextual help |
C-c p c |
Open customization |
Press RET on a file link to open text files as ordinary Emacs buffers. HTML, PDFs, images, videos, and binaries open with macOS open
The default is localhost:5000, sharing chats with emacs but with a browser-native layout, appearance settings, and attached convo images. Use Ctrl+K / Cmd+K to traverse through the app
There's an emacs tutorial as well if you want to visit it through Ctrl+K / Cmd+K
An orange m# is your manager. It answers small requests and delegates larger ones to purple b# bots, or resumes an existing bot. Managers have no assigned location, they choose named working directories for bots. Their own Codex process starts in your home directory. A bot's gray badge shows its location
Their instructions live in ~/.cache/aibo/docs/ (or $AIBO_CACHE_DIR/docs/).
Missing m.md, b.md, and sb.md files are seeded from bundled defaults;
existing files are never overwritten, so you can customize them freely.
aibo/api.md is managed by Aibo and refreshed from the bundled reference at
server startup and whenever role instructions are loaded; local edits are overwritten.
| File | Purpose |
|---|---|
m.md |
Coordination and delegation |
b.md |
How a worker carries out its task |
sb.md |
How outcomes are summarized |
aibo/api.md |
API guide used by the assistants |
Note that their numbers are convenient labels and eventually repeat ([0,255] inclusive range) to help with referencing to chats by shortnames (e.g. "can you check why b3 crashed?")
Hidden shadow bots (sb) summarize finished work for notifications, and separate short-lived Codex threads generate titles, neither clutters your conversation search
Each project expects a README.md in ~/.cache/aibo/projects/{project_name}/README.md for m# and b# to have context, just ask m to update/create one for you
| Client | Open customization |
|---|---|
| emacs | C-c p c |
| web | Ctrl+K / Cmd+K, then choose Customization |
C-M-h does this automatically, or run it yourself:
python -m aibo.cli.deploy ensureRebuild the server, web assets, and Emacs code, then reload an existing Emacs daemon without restarting the bouncer:
python -m aibo.cli.deploy redeployRestart just the Codex bouncer, this can interrupt active work:
python -m aibo.cli.deploy bouncer-redeployRebuild the server and UI and restart the bouncer, with the same interruption risk:
python -m aibo.cli.deploy redeploy --redeploy-bouncerSet aibo:server-url for another local port, or aibo:auto-start to nil for a server you manage yourself
Local startup keeps PostgreSQL, connection settings, and logs under ~/.cache/aibo. AIBO_CACHE_DIR changes that root, AIBO_DATABASE_URL selects an existing database
For nginx blue/green deployment, see deploy/nginx and set AIBO_PUBLIC_URL. Use one process manager per service, don't mix launchd-owned services with the CLI's managed processes
GitHub Actions runs on pull requests, pushes to main, and manual requests, without deploying or starting real Codex turns
| Check | Coverage |
|---|---|
| Backend | Black, isort, Ruff, mypy, migrations, and Python tests with disposable PostgreSQL |
| Web | Prettier, ESLint, tests, TypeScript, and a production build |
| Emacs | Native formatting and syntax, strict byte compilation, ERT, and terminal behavior tests |
Branch protection needs to require these checks separately. Browser screenshot tests and the full terminal reference matrix aren't CI gates
| Directory | Contents |
|---|---|
elisp/ |
Emacs entry point, API, search, settings, and UI modules grouped by responsibility |
elisp/tests/ |
ERT tests and independent terminal reference fixtures |
python/src/aibo/core/ |
Workspace rules, model settings, and title generation |
python/src/aibo/server/routes/ |
API routers grouped by resource, with shared HTTP helpers |
python/src/aibo/bouncer/ |
Codex transport and session management |
python/src/aibo/cli/ |
Local startup, deployment, and migrations |
python/src/aibo/db/ |
Database access and models |
web/src/pages/ |
Main-panel views |
web/src/components/ |
Shared UI components, composer, sidebar, and dialogs |
web/src/hooks/ |
Browser event, keyboard, and attachment integrations |
web/src/state/ |
Observable workspace and search state shared by views |
web/src/tutorial/ |
Guided tutorial and generated terminal frames |
deploy/ |
Deployment configuration templates, not local process state |