Autonomous AI coding agent with persistent memory, TUI, and Telegram control
→ leanproiq.com · Windows guide · styled version
Architecture and design by Dušan Milosavljević — Da Nang, Vietnam
Built with modern coding tools — Claude Code among them — used throughout.
What is Aura?
Aura is a model-agnostic autonomous coding agent. Give it a task in natural
language — it reads your codebase, plans, executes, verifies, and reports back.
Why Aura
A framework, not a turnkey product — and it still starts with one command.
Most coding agents are appliances: you get the workflow their authors chose, and
customising it means waiting for them. Aura is built the other way round. The
model is yours to pick (31 routing targets over four transports, or any
OpenAI-compatible endpoint, or a local model with no key at all), the tools are
yours to extend, and the parts you add are ordinary files you can read, edit
and share.
That costs you nothing at the start — npm install -g aura-code and a task in
plain English is the whole first run. The framework is there when you want it,
not homework before you begin.
And unlike an appliance, she accumulates.
She works, captures what happened, learns which tasks she is competent at,
routes those to a local model and saves the expensive one for the hard parts —
and turns the whole record into a dataset that belongs to you.
1. She remembers — lessons, not chat history.
What broke last time, what your build actually needs, what you told her once and
should not have to repeat. Stored in ~/.aura/memory/ on your machine. It never
leaves it.
2. She learns what she can handle alone.
The Archimedes layer scores her competence per project and per task category,
then alternates: a local model for what she has proven she can do, a frontier
model for what she has not. Cost falls as she improves, instead of staying flat
forever.
3. She builds you a dataset you own.
:mine turns your sessions into structured training examples in
training-data/, and competence tracking tells you when you have enough to
fine-tune. The training run itself is yours to make — Aura assembles the raw
material, which is the part nobody else gives you.
4. She grows new parts on request.
Skills, plugins, MCP servers, subagents. "I want a travel agent" is an ordinary
request here, because a skill is a file and writing files is what she does — so
extending her is a conversation, not a pull request against someone else's
roadmap. The capability she builds is yours to keep, edit and share.
The tools reach past the codebase — email, calendar, telegram,
whatsapp, cron, browser, and on Linux a computer tool that sees the
screen and drives the pointer. Same memory, same agent, so what she learns
working on your code is there when she is handling the rest of your day.
Most agents are something you use. Aura is something that compounds.
Quick Start
npm install -g aura-code
export DEEPSEEK_API_KEY=sk-...
aura 'refactor the auth module to use JWT'
Optional but worth it: with RTK (Rust Token Killer) on PATH, Aura's shell
and git tools route through it, compressing command output before it reaches the
context window — 80% fewer input tokens per session, measured. Without it they
run the bare command exactly as before. AURA_RTK=0 opts out.
Features
- Autonomous execution — reads files, edits code, runs shell commands, verifies, retries
- Mid-run steering — type while it works; the note is folded into the next turn, not a restart
- Finishes rather than stalling — on a stall it works out what it was missing, then carries on
- Learns durably — what it worked out is written down and read back in every later session
- Gazelle mode — a lean conversational path for everything that isn't a coding task; 26x less context per turn
- The Archimedes Principle — a small local model attempts tasks first; the cloud model steps in only when needed
- Full TUI — terminal UI with command palette, diff view, markdown rendering, vim-style input
- Persistent memory — identity, lessons, and project context survive across sessions
- Telegram bot — voice notes, PC control, file transfer, webcam snapshots
- 31 routing targets, 4 transports — DeepSeek, Claude, GPT, Gemini, GLM, MiMo, Ollama, OpenRouter and more
- Token efficiency — tiered context strategy, prompt caching, tool relevance gating
- MCP support — Model Context Protocol for external tool connections
Visual Showcase & Aura Web Studio
aura serve opens the web studio (web/): chat, a drag-and-drop Kanban board
with a workflow graph, a canvas for live previews, and a code editor with a
real terminal. It wears the same Nature identity as the terminal UI.
| Workflow graph | Execution list |
|---|
| |
| Canvas | Code editor and terminal |
|---|
| |
| Agents | Providers and models |
|---|
| |
| Approval and sandbox | Terminal UI |
|---|
| |
Gazelle — conversational mode
Most of what you say to a coding agent isn't a coding task. "What did we decide
about the auth flow?" doesn't need 25 tool schemas and a project tree — but the
coding agent sends them anyway, every turn.
Gazelle is the same Aura on a different path: no tool schemas, no project
context, no Archimedes, no verification gate. Just the conversation.
aura --gazelle # or: aura --mode gazelle
AURA_MODE=gazelle aura # or set it in the environment
You can also switch inside a running session: /gazelle for the lean path,
/coder to go back to the full agent.
What it costs
Measured on this repo with Aura's own tokenizer (estimateContextTokens, the
same one :context reports with):
| Per-turn fixed context | Coder | Gazelle |
|---|
| System prompt + project context | 4,793 | 356 |
| Tool schemas (25 tools) | 4,574 | 0 |
| Total every turn | 9,367 | 356 |
26x less context per turn — 9,011 tokens saved on every message.
Over a whole conversation the gap widens well past that, because the coding
agent's history also accumulates file contents and tool output while Gazelle's
does not. How much further depends entirely on how many tools a given session
calls, so that multiple is an observation about a session, not a number this
project will quote as a spec.
Switching mid-session
Neither mode is a dead end, and conversation history carries across:
:coder → hand off to the full coding agent (tools, project context)
:gazelle → drop back to the lean conversational path
Gazelle also notices when it needs tools and offers to switch on its own —
recognized from its own wording, not a second model call, so the detection is
free. Answer y (or just press Enter) and it hands off with the conversation
intact.
Both commands work in the ordinary aura REPL too, not just a session started
with --gazelle: the TUI stays where it is and swaps only what a turn does, and
the status line grows a gazelle marker so the cheap path is never a guess. In
the REPL, Enter submits a line rather than accepting an offer, so a reply that
wants tools points at :coder instead.
Memory
When a Gazelle session ends it writes a rolling situational summary — what you
were working on, what was unresolved. Not a transcript, not a fact dump. The
next session opens already knowing where you left off and uses that as
background, rather than opening with "I recall that…".
What it isn't
Gazelle can't read files, search code, or run anything. That's the point — it's
the front door, not the workshop. When a request needs hands, :coder is one
word away.
Providers
| Provider | Models |
|---|
| DeepSeek | deepseek-v4, deepseek-v4-flash |
| Claude (Anthropic) | Opus 4, Sonnet 4.6, Haiku |
| GPT (OpenAI) | gpt-4o, gpt-4o-mini |
| Gemini (Google) | gemini-2.5-pro, gemini-2.5-flash |
| GLM (Zhipu / Z.ai) | glm-5.2, glm-5.1, glm-5 — zhipu-coding/ routes via the Coding Plan |
| MiMo (Xiaomi) | mimo-v2.5-pro, mimo-v2.5 (mimo/, xiaomi/) |
| Ollama | any local model (ollama/, local/, local-profile/) |
| LM Studio | any loaded model (lmstudio/) |
| OpenRouter | 100+ models |
| Groq | llama, mixtral |
| xAI (Grok) | grok-2, grok-2-mini, grok-beta |
| BytePlus ModelArk | DeepSeek V4 Flash/Pro GA, Seed, Kimi (byteplus/) |
| FPT Cloud AI | DeepSeek V4, GLM-5.2, Qwen3.8, Gemma 4, GPT-OSS, Embeddings (fpt/) |
| OpenCode Go | MiniMax M3/M2.7, Kimi K3 and more (go-anthropic/) |
| OpenCode Zen | free tier — DeepSeek V4 Flash, Ling 3.0, MiMo V2.5 (zen/) |
| OpenCode | opencode/ |
| NVIDIA NIM | any NIM-hosted model (nvidia/) |
| Hugging Face | Inference Providers router (huggingface/) |
| Kimi (Moonshot) | any Moonshot model (kimi/) |
| Qwen (DashScope) | any DashScope model (qwen/) |
| MiniMax | any MiniMax model (minimax/) |
| StepFun | any StepFun model (stepfun/) |
| Fireworks AI | any Fireworks model (fireworks/) |
| Upstage | Solar models (upstage/) |
| Arcee AI | any Arcee model (arcee/) |
Thirty-one routing targets, but not thirty-one integrations. They collapse onto four
transports: AnthropicProvider and GoogleProvider for the two wire formats
that differ, OpenAICompatibleProvider for everything else, and
ArchimedesModel for the local small-model path. Adding a provider is a base
URL, an API key env var, and a model-id rewrite — not a new class.
The Archimedes Principle
Aura's local+cloud alternation system. A small local model — "Archimedes" — attempts tasks first; a large cloud model escalates in only when Archimedes can't be trusted with the task or its answer fails verification. Every alternation is captured as an episode, and Archimedes's track record decides how much it gets trusted next time.
The name reflects the design: a small model, present from the beginning, that learns from every episode where the large model had to intervene.
The local model
The shipped code default is qwen2.5-coder:1.5b via Ollama. In practice this project runs IBM Granite 4.1 (3B) (granite4.1:3b), which proved notably accurate for its size in testing — set it via archimedes.modelName in .aura.json (example below). Any Ollama model tag works.
Competence-based routing
Before each task, assessCompetence checks Archimedes's historical success rate on similar tasks (token-overlap similarity against the last 50 episodes):
- Fewer than
minAttempts (default 3) prior attempts on a pattern → Archimedes always gets a chance, to gather training data.
- Success rate ≥
competenceThreshold (default 0.7) → Archimedes handles the task.
- Below threshold after enough attempts → escalate straight to the large model.
If Ollama isn't reachable, Aura escalates immediately rather than hanging.
The verification gate
When Archimedes produces an answer, it is not trusted just for being non-empty. A single cheap complete() call (no tools, no history) asks the large model whether the answer actually addresses the task; anything other than a clear VALID — including verification errors — escalates to the large model. This exists because a small model's most dangerous failure mode isn't crashing, it's a confident-but-wrong answer or silent drift off-task.
Runtime toggle: :archon / :archoff
In the interactive TUI you can override .aura.json's archimedes.enabled for the rest of the session:
:archon — force Archimedes routing on, even if the config file has it disabled:archoff — force everything to the large model, even if the config file has it enabled
The override lasts for the current session only; restart returns control to the config file.
Configuration
.aura.json's archimedes block:
{
"archimedes": {
"enabled": true,
"modelName": "granite4.1:3b",
"ollamaBaseUrl": "http://localhost:11434/v1",
"competenceThreshold": 0.7,
"minAttempts": 3
}
}
When enough Archimedes failures accumulate (20 by default), Aura flags the project as ready for fine-tuning — failed episodes become instruction-tuning rows for the local model.
Performance note: if you run Archimedes on an AMD iGPU via Ollama and see local-model calls hang for minutes, the Vulkan backend's prefill throughput may be far below CPU on your hardware. Running Ollama CPU-only (e.g. hiding the Vulkan device via GGML_VK_VISIBLE_DEVICES) restores usable speed.
CLI
aura 'your task' # run a single task
aura # interactive TUI
aura serve # start the HTTP API server
aura --auto 'task' # fully autonomous, no confirmations
aura --readonly 'analyze' # read-only analysis
aura --sandboxed 'refactor auth' # kernel-enforced boundary (Linux)
aura --doctor # self-diagnostic
Flags
| Flag | Description |
|---|
--model, -m <id> | Model to use (default: saved global config / AURA_MODEL) |
--api-key <key> | API key (overrides env var) |
--base-url <url> | Custom API endpoint (Ollama, proxies, etc.) |
--auto | Auto-approve all tool calls (no confirmation) |
--readonly | Read-only mode (no file writes or shell commands) |
--sandboxed | Kernel-enforced boundary: Aura's own install is read-only and writes outside the project fail at the OS level. Linux + bubblewrap; refuses rather than pretending elsewhere. Not combinable with --computer. See SECURITY.md |
--gazelle | Gazelle mode: lean conversational path, no tools |
--mode gazelle | Same as --gazelle (env: AURA_MODE=gazelle) |
--cwd <path> | Working directory (default: current) |
--models | List all known model IDs |
--interactive | Start the interactive REPL/TUI |
--no-session | Disable conversation history persistence |
--new-session | Force a fresh session (ignore prior history) |
--resume [id] | Resume latest session, or a specific session by ID |
--chat-id <id> | Attach to a specific chat ID (creates if missing) |
--list-sessions | List all saved sessions for this project |
--no-setup | Skip the first-run setup wizard |
--reset-setup | Wipe saved config and re-run the setup wizard |
|
CLI flags always override .aura.json.
REPL commands
Inside the interactive TUI (press Ctrl+P for a fuzzy-searchable command palette):
Modes
| Command | Description |
|---|
:coder | Switch to full coding-agent mode (tools, project context) |
:gazelle | Switch to lean conversational mode |
Session
| Command | Description |
|---|
:id | Show current chat ID |
:sessions | List all saved sessions |
:resume / :resume <id> | Resume the latest (or a specific) session |
:new | Start a new session (fresh history) |
:history | Show turn count in current session |
:clear-history | Wipe conversation history (keep session ID) |
:save [title] | Rename / save current session |
:delete <id> | Delete a saved session |
Model / API
| Command | Description |
|---|
:model / :model <id> | Interactive model selector / direct switch |
:provider | Pick provider, then model (live-fetched lists) |
:apikey <key> | Set API key for current session |
Workflows / tasks
| Command | Description |
|---|
:workflows | List all saved workflows |
:workflow <name> "step1" "step2" ... | Create & run a multi-step workflow |
:resume-workflow <id> | Resume a paused/failed workflow |
:q add <prompt> / :q list / :q run <n> / :q drop <n> / :q clear | Task queue |
:machina <task> | Run task with self-verification + auto-retry |
:council <task> | 2–3 parallel read-only specialists, then synthesis |
:ecclesia <topic> | 5 independent research agents + synthesis verdict |
Memory / side channel
| Command | Description |
|---|
:dream / :dream full | Consolidate recent (or all) episodes into a dream entry |
:rem | Show reconciled memory (or latest dream) |
:mine / :mine --refine | Mine episodes for patterns (zero-LLM clustering) |
:research <topic> | Multi-step research pass, saved to research/*.md |
:confess / :confessions | Auto-detect & list anomalous-episode confessions |
:btw <question> | Quick side question (read-only, no history pollution) |
:lessons | Everything Aura has learned, both scopes, with keys |
:lessons global / :lessons project | Only that scope |
:lessons timeline | When lessons were learned, as a per-day chart |
:lessons <text> | Only lessons matching that text |
:forget <key> | Remove one lesson from the prompt for good |
Computer use
| Command | Description |
|---|
:compon | Turn computer use ON (shows the disclosure first) |
:compoff | Turn it OFF and release the input device |
:comp | Show whether it is on, and what is holding it there |
While a task is running
| Command | Description |
|---|
| anything else | Steers the running task — folded in at the next turn |
:stop / :cancel | Abort the running task |
Design
:designx treats a design ask as a commission rather than a coding ticket: it routes 2–3 named
directions out of a hand-written style lexicon (Swiss International, Risograph Misprint, Cassette
Futurism, Blueprint, …), sends the agent to scrape real references for those specific directions,
then builds a self-contained artefact into design/. The lexicon exists to stop the run converging
on the default AI page — centred hero, gradient headline, three rounded cards.
| Command | Description |
|---|
:designx <brief> | Route a direction, scrape references, build the artefact |
:designx web|deck|pdf <brief> | Force the artefact type (otherwise inferred from the brief) |
--classic / --wild / --feral | How far past convention to push (default: balanced) |
--style <id> | Pin a direction from the lexicon (repeatable, comma-separated) |
--seed <n> / --count <n> | Re-roll reproducibly / how many directions to route |
--no-scrape / --out <dir> | Skip the reference pass / choose the output directory |
:designx styles | List the lexicon |
Output is one self-contained file per target — index.html (web), deck.html (arrow-key slides,
one slide per printed page), document.html (A4 paged media, rendered to PDF via headless Chrome
when one is installed) — plus a DESIGN.md recording which direction it led with and why.
Archimedes
| Command | Description |
|---|
:archon | Enable Archimedes Alternator for this session (overrides .aura.json) |
:archoff | Disable Archimedes Alternator for this session (overrides .aura.json) |
Voice / safety
| Command | Description |
|---|
:speak | Toggle reading replies aloud |
:approve / :approve all / :approve off | Auto-approve controls for y/N prompts |
Context / stats / system
| Command | Description |
|---|
:compact, :compress | Force context compaction now |
:context | Show loaded project context |
:graph / :graph refresh | Codebase knowledge graph summary / reload |
:plans | List saved execution plans |
:viz, :dashboard | Generate and open the memory dashboard |
:doctor / :doctor --fix | Scan Aura itself for issues / attempt repairs |
/stats, /usage | Token + cost usage this session |
/cost [n] | Cache hit rate + cost per call (default: last 20) |
/context | Context health dashboard (window, compaction, cost) |
/context tune, /ct | Adjust when compaction fires (←/→ on the ladder) |
/clear, /reset | Reset cumulative usage stats — does not clear history (use :clear-history) |
:help | Show all commands |
:quit, :q, /exit | Exit |
Steering, and finishing
Two behaviours that have no command because they are simply how a run works.
Steering. The TUI never stops reading your keyboard while a task runs. Type
a plain line mid-task and it is parked, then handed to the model at the next
turn boundary — the run keeps its history, its tool results and its plan, and
just learns one more thing:
↳ queued — Aura picks this up on the next turn.
↳ steering use tabs, not spaces
Commands still wait for the run to end: :model, :new and :compact mutate
state the running loop is holding. :stop still aborts.
Finishing. A run that hits its turn cap or stalls used to return "Loop
stalled" and throw away everything it had learned. Now, once per run, at the
point where the run was already lost:
turn 22/25 → stall
↳ name what you do not know one cheap call, no tools
↳ search what Aura already learned free — no LLM call
↳ …on a miss, research it read-only, 5 turns
↳ resume the original task
↳ write the lesson down next time this gap is free
Memory is searched before anything is spent, which is the whole reason lessons
are written down in the first place. Facts about the world go to
~/.aura/memory/lessons-global.md and apply everywhere; facts about one repo
stay in its .aura/lessons.md. Read them with :lessons, drop a wrong one
with :forget. Skipped entirely if you abort, or if a budget ceiling has
fired — the ceiling that just stopped the run is not something a recovery pass
should spend through.
Cost controls
A long agent session is expensive in a way that isn't visible while it runs.
The history is resent on every call, so per-call input cost grows linearly and
total cost grows quadratically — and a session can look fine by turn count
while being the expensive one. Aura guards this at three levels.
Compaction threshold. Compaction fires at min(window * rung, context.maxTokens),
default cap 80k tokens. The cap matters on large-window models: as a pure
share of the window, rung 1 on a 1M-window model sits at 550k, so a session
can grow indefinitely without ever compacting. Tune the ladder live with
/context tune (short: /ct), or set context.ladder / context.maxTokens
in .aura.json. On a large-window model the 80k cap is usually what's
binding, not the ladder — the tuner marks rungs held at the cap and tells you
when the ladder has no effect at all.
Session budget. Two cumulative ceilings across a whole conversation, not
per agent-loop invocation:
| Ceiling | Default | What it's for |
|---|
| Turns | 50 (--max-turns) | Coarse backstop for when caching doesn't save you |
| Input tokens, net of cache hits | 1M | The one that tracks actual spend |
Both are needed because turns are a poor proxy for cost. Cache hits bill at a
fraction of the standard rate — on GLM-5.2, $0.26 vs $1.40 per Mtok — so a
well-cached 50-turn session and a cold one cost wildly different amounts for
the same turn count. The token ceiling measures what you actually pay for; the
turn cap catches runaway loops. Whichever binds first stops the run, and it
stops cleanly: the current turn finishes and history is persisted, so the
session stays resumable.
In the interactive REPL, only the token ceiling is cumulative. You are
typing every message and watching every response, so a session-wide turn
cap would interrupt a cheap, supervised conversation for crossing a count
that says nothing about its cost — one real 96-minute session ran 58 turns at
a 86% cache hit rate for $0.50. The per-message --max-turns guard still
applies and is what actually catches a runaway loop.
The turn cap is 50, not the previous 150. Expect --max-turns to be routine
for real project work, not just something benchmark runs pass.
Stalled streams. A cloud provider's SSE stream can go silent without the
connection closing — no error, no end-of-stream, just nothing. The provider
SDKs don't catch this: their timeout option only covers time-to-headers, not
the streamed body. Aura applies its own idle timeout between chunks
(default 60s); on a stall it aborts the request and retries once, but only if
nothing has been displayed yet — retrying after partial output would duplicate
the response. Tune with AURA_STREAM_IDLE_MS (ms; 0 disables).
Visibility. /cost reports cache hit rate and per-call cost from
.aura/token-log.jsonl, including what the same input would have cost
uncached. Hit ratio is the dominant lever: in one measured session, 19.5M
tokens at a 98% hit rate cost $1.04, while 7.75M uncached tokens cost $7.90 —
the same work, 7.6x cheaper.
Memory System
Persistent memory across sessions — identity, lessons from past failures, session summaries. Stored locally, never leaves your machine.
Everything lives under ~/.aura, or wherever AURA_HOME points if you set it:
| Path | What |
|---|
~/.aura/memory/identity.json | Who you are and settled facts |
~/.aura/memory/lessons-global.md | Lessons true everywhere — read in every project |
<project>/.aura/lessons.md | Lessons true only in this repo |
~/.aura/episodes/ | What happened, in the order it happened |
~/.aura/confessions/ | Permanent lessons from high-cost failures |
Read what Aura has learned with :lessons; drop a lesson that turned out wrong
with :forget <key>. These are injected into the system prompt, so a wrong one
left in place gets repeated back to you until it is removed.
Running as a service
aura setup telegram generates a ready-to-use unit at
~/.config/systemd/user/aura-telegram.service, which is the supported route —
it fills in the paths for your machine rather than leaving you to edit them.
Hand-written reference units (aura.service for the CLI in a tmux session,
aura-telegram.service, rclone-gdrive.service) are kept outside this
repository, since they carry absolute paths for one specific machine and are
deployment glue rather than part of the package. Adjust User,
WorkingDirectory and ExecStart before reusing any of them.
cp aura-telegram.service ~/.config/systemd/user/
systemctl --user daemon-reload
systemctl --user enable --now aura-telegram.service
Run the compiled build, not npx tsx
If you write your own unit for any Aura entrypoint, point ExecStart at the
compiled JS with plain node:
ExecStart=/usr/bin/node /path/to/aura-code/dist/tools/telegram-bot.js
Not npx tsx src/tools/telegram-bot.ts. tsx isn't a dependency of this
project, so npx re-resolves and installs it from the network on every start —
which pins a CPU core at 100% for the life of the unit, bloats ~/.npm/_npx by
gigabytes, and never reaches the program's first log line. It looks exactly like
a hang with no error. This cost one production incident here; the compiled build
starts in under a second.
Trade-off: npm run build is then required after editing src/, since nothing
transpiles on the fly anymore. Use /usr/bin/node rather than an nvm path —
nvm paths pin a node version and break on upgrade.
Restart policy
[Unit]
StartLimitIntervalSec=300
StartLimitBurst=5
[Service]
Restart=on-failure
RestartSec=15
StartLimitIntervalSec / StartLimitBurst cap total restart attempts in a
window: after 5 failures in 5 minutes systemd gives up instead of looping. Note
they are [Unit] directives — systemd silently ignores them under
[Service], which makes a policy that looks correct do nothing.
Worth knowing what this does and doesn't buy you: the Telegram bot's poll loop
already handles Telegram 409 Conflicts in-band (5s pause, then exponential
backoff) and its uncaughtException handler deliberately doesn't exit. A bot
that never exits is never restarted, so restart policy is a guard against
future failure modes that do exit — not a fix for a busy-looping process.
Where this is going
Persistent memory across projects, space and time — and the datasets that come
out of it. Every session Aura works through leaves behind something a future
model can learn from, which is the long way round to a question worth asking:
how much of what we call awareness is just a record that never gets thrown away.
That is the ambition. The parts of it that already run are documented above; the
rest is being built in the open.
License
MIT © Dušan Milosavljević
Website: leanproiq.com
