You do what matters. Else handles the rest.
else-bot is a local-first personal agent runtime for work that spans more than one prompt, tool, or session. You define the outcome and its boundaries; else keeps the thread alive, decomposes it into scopes, dispatches execution, verifies the result, and asks for your attention only when a decision belongs to you.
The product metric is simple: how much human attention does each completed outcome cost?
Agentic tools are good at producing output. They are much worse at owning a commitment.
A real outcome usually needs several runs, external context, approvals, retries, and follow-up. Without a durable control plane, the work turns into a stream of chats and notifications that you have to coordinate yourself:
- context is repeatedly lost between conversations and tools;
- plans change without a record of why;
- external changes are discovered too late;
- retries repeat side effects;
- every intermediate update competes for attention;
- the final result is difficult to verify or audit.
else-bot exists to make the thread, not the chat transcript or agent run, the durable unit of work.
- Keeps thread state durable. Plans, scopes, and agent runs are disposable; the outcome, constraints, decisions, and evidence survive.
- Coordinates execution. Codex and Claude Code can run behind one harness contract, with local scheduling, isolated workspaces, budgets, and retries.
- Treats attention as a resource. Requests are persisted and ruled as silent, deferred, batched, or interrupting instead of becoming notifications.
- Tracks the outside world. Calendar, Linear, and Notion observations become replayable signals and candidates rather than directly creating work.
- Requires authority for side effects. External actions pass through the Tool Gateway with approval, idempotency, verification, and compensation.
- Exposes one runtime to every surface. The CLI, terminal UI, and future clients speak the same HTTP API against the same local daemon.
macOS and Linux:
curl -fsSL https://github.com/narcilee7/else/raw/refs/heads/master/install.sh | shThe script downloads the matching release binary, verifies SHA256SUMS, installs
else, prepares the runtime directory, and runs first-run setup.
brew install narcilee7/tap/else-botIf Homebrew asks for explicit trust on first use:
brew trust narcilee7/tapThe first crates.io publication is still pending account authentication. Once published, the install command is:
cargo install else-bot --lockedelse-bot onboard # prepare the runtime and background service
else-bot doctor # environment, daemon, token, ledger, and connector health
else-bot # open the terminal interfaceThe first screen is a personal brief, not a chat window.
Create a durable thread:
# in a directory you already own
else-bot thread "Summarize this week's meeting notes" --in ~/notes
# or in an isolated scratch directory owned by the runtime
else-bot thread "Prepare the release and verify every platform artifact" --project releaseInspect what needs attention:
else-bot brief
else-bot decisions <thread-id>
else-bot world <thread-id>Drive work and inspect the evidence:
else-bot advance <thread-id> --harness auto
else-bot plan <thread-id>
else-bot resources <thread-id>
else-bot log <thread-id>Run the shared runtime explicitly:
else-bot serve --bind 127.0.0.1:4180The daemon uses a local Bearer token, remains the only writer, and lets the CLI, TUI, and other clients observe the same state.
Thread
-> Context and external signals
-> Plan and execution scopes
-> Harness or tool through the Gateway
-> Artifact and effect verification
-> Outcome with evidence
The runtime is event-sourced. Thread state, decisions, artifacts, side effects, resource usage, retries, and verification are projections of an append-only ledger. Replaying a ledger should reconstruct the same state.
The local-runtime boundary is deliberate:
CLI / TUI / future surfaces
|
authenticated HTTP
|
else-daemon
|
SQLite ledger + artifacts
The terminal UI includes:
- Today: decisions, active work, recent outcomes, commitments, and risks;
- Decisions: a review queue plus full context, options, custom responses, and explicit confirmation for high-impact approvals;
- Results: finished outcomes, acceptance criteria, and produced artifacts;
- Settings: connector health, credentials, and synchronization.
Thread details keep scopes, resource accounting, and raw events behind an explicit debug toggle.
The CLI accepts --json globally for automation and scripting. Successful commands
write exactly one JSON document to stdout. Runtime and argument failures write
{"error":{"kind":"api|client|usage","message":"..."}} to stderr and return a
nonzero status. Existing read-only result shapes remain unchanged; write commands
return their resulting domain object or a named object for composite results.
tool-call is the exception: it preserves the Tool Gateway response body.
else-bot thread "Prepare the release" --json
else-bot decisions <thread-id> --json
else-bot --json # non-interactive personal brief- execution is sandboxed by default;
- network access is deny-by-default;
- external writes require explicit authority;
- credentials are stored outside the event ledger;
- provider actions are idempotent and verified;
- opaque agent-tool effects are observed and accounted separately from Gateway-authorized actions;
- uncertain external results are surfaced rather than blindly retried.
else-bot is currently a single-user, single-machine runtime. It is not yet a multi-tenant cloud service, and irreversible external actions cannot be fully rolled back.
Releases use semantic versions:
- stable:
v0.1.0,v0.2.0,v1.0.0; - beta:
v0.2.0-beta.1,v0.2.0-beta.2; - release candidate:
v0.2.0-rc.1.
0.x is initial development: interfaces may still change between minor
versions. 1.0.0 marks the first compatibility promise.
Beta and RC tags are published as GitHub prereleases. They are not marked
Latest and do not update the Homebrew stable formula.
Releases are cut in CI, not from a laptop. Actions → Cut Release → Run
workflow takes a bump (patch/minor/major/none) or an explicit version such
as 0.2.0-beta.1, and a dry-run switch. It:
- runs format and the full test suite on
master, - rewrites the version in every
Cargo.toml, the README and the release workflow's default (scripts/bump-version.py, also runnable locally), - commits
chore: <version>and pushesv<version>,
and then the tag triggers Release CLI, which builds the four targets, creates the GitHub Release, and updates the Homebrew formula and tap. Nothing after step 3 needs a human.
Manual scripts/release.sh <version> still exists for local dogfood artifacts;
it does not publish.
| Platform | CLI/TUI | Tested in CI | Sandbox | Networked harnesses |
|---|---|---|---|---|
| macOS arm64 | Supported | yes | seatbelt | yes |
| macOS x86_64 | Supported | build only | seatbelt | yes |
| Linux x86_64 | Supported | yes | bubblewrap | no |
| Linux arm64 | Supported | build only | bubblewrap | no |
"Build only" means a release artifact exists but no test runs on that
architecture. On Linux, harnesses that open their own network connections
(claude-code, codex) are refused: bubblewrap cannot enforce the local
allowlist proxy that macOS gets from seatbelt, and else fails closed rather
than letting an agent out with no allowlist. else-bot doctor reports which
backend this machine has and what it can enforce.
Details, including how to avoid the class of bug that only appears on the other OS, are in docs/platforms.md.
macOS CLI archives are ad-hoc signed until Developer ID credentials are available. The macOS App is not part of the current public release line.
Use the isolated development runtime rather than the installed background service.
It lives in .else/dev, listens on 127.0.0.1:4181, and never requires onboarding
or modifying the production runtime. Every command builds the current source first.
Start the daemon in one terminal:
./scripts/dev.sh servePopulate deterministic demo data and open the TUI in another terminal:
./scripts/dev.sh seed
./scripts/dev.sh tuiThe seed command is idempotent and creates a pending decision, a completed result, and work waiting for an external event. It uses the built-in scripted harness, so it does not need provider credentials or network access. Python 3 is required for seeding and reset safety checks.
Run CLI commands against the same development runtime:
./scripts/dev.sh cli list
./scripts/dev.sh cli brief --json
./scripts/dev.sh cli decisions <thread-id>After changing only the TUI, rebuild and reopen it; the daemon can stay running. After changing the API, daemon, or shared protocol, restart both processes. Stop the daemon before clearing the development data:
./scripts/dev.sh resetFor another isolated checkout or runtime, set ELSE_DEV_RUNTIME_DIR and optionally
ELSE_DEV_BIND. Reset refuses paths outside this repository's .else directory
and refuses to delete a runtime whose foreground daemon is still running.
Run the complete Rust validation suite:
./scripts/dev.sh check
cd surfaces/apple
swift testBuild a local CLI artifact:
scripts/release.sh 0.1.3Build internal release artifacts without Apple credentials:
gh workflow run release-cli.yml -f version=0.1.3 -f publish=false