Alisio
Alisio is your coding agent, on the model you choose. It connects any OpenAI-compatible model
to your project and drives its own tool loop: it reads and edits code behind explicit permissions,
and when code is the faster route it writes and runs it with Forja, isolated JavaScript to combine
tools and Python for data analysis, AI and dashboards. It runs in your terminal (TUI or headless for
scripts and CI) and in your browser with alisio serve. It also compacts long conversations into
structured checkpoints, remembers decisions across sessions with persistent memory (a built-in plugin
you can disable), and exposes a typed plugin SDK so you can extend it without touching the core.
Status: stable, tested and documented, still pre-1.0. Until 1.0.0 the usual 0.x semver rules apply: fixes ship as patch releases and a new minor release may include breaking changes. The npm badge above always shows the latest published version; see the limitations and Stability and versioning.
Highlights
- Terminal UI: streaming Markdown, tool blocks with spinners, durations and diffs, a context/token bar, slash commands with autocomplete, model switching, interactive approvals and copy-on-select.
- Web UI:
alisio serveopens a local, token-protected browser workspace for several workspaces and sessions, with streaming conversations, approvals, files, changes, artifacts and the plan viewer, on the same agent core. - Any OpenAI-compatible provider: Chat Completions and Responses APIs, DeepSeek-style endpoints, local servers.
Keys are read from environment variables only. Dedicated DeepSeek, OpenCode Console (Zen) and
OpenCode Go providers are separate plugins:
alisio install npm:@alisio/plugin-deepseek,alisio install npm:@alisio/plugin-opencode,alisio install npm:@alisio/plugin-opencode-go. - Local tools with explicit permissions: reads by default; the TUI asks before every
write/process/network call unless you pass
--allow-write/--allow-process/--allow-external(skip asking) or--read-only(never even offered). Alisio as a whole is not a sandbox, and it says so: only Forja isolates code. A repository's own.alisio/config.jsonand plugins load only after a one-time per-directory trust prompt (or--trust-project). - Context compaction: a structured checkpoint (goal, constraints, discoveries, state, next steps, files) that never splits tool calls from their results.
- Persistent memory: SQLite FTS5 observations, topic-key upserts, memory-aware compaction and
session summaries, shipped as the disableable
@alisio/plugin-memory. - Agents: create agents with the active model's help (or from templates), stored as portable
Markdown in
.agents/agents(project) or~/.agents/agents(global), reloaded without a restart and switched with/agentsor/agent:<id>in the web UI and the TUI. - Plan mode and plan viewer: a read-only plan agent proposes a plan (with optional Mermaid diagrams) that you approve before anything changes; the web UI opens it in a plan viewer.
- Forja, code mode picked by goal:
js_runruns JavaScript in a fresh QuickJS WebAssembly VM with no file, network or process access, to combine tool calls, filter results and transform data under the agent's own permissions.python_runhandles data analysis, statistics, scikit-learn, charts and custom dashboards in a container (oci) or a restricted Pyodide process (wasm) when available, andanalysis.isolation: requiredkeeps it off your host. Guides load on demand withforge_guide, and each session gets a private scratchpad. See the Forja docs for the isolation limits. - Dashboards and charts: Python analysis publishes dashboards, reports and spreadsheets as artifacts, with interactive charts from an embedded Chart.js that works offline.
- Reliability Lab:
alisio evalruns task suites k times with deterministic verifiers, reports pass rates with Wilson intervals, compares reports and config variants, and replays recorded cassettes to catch harness regressions without a model (replay measures the harness, not the model). See the Reliability Lab docs. - Proof: acceptance criteria whose status comes from evidence Alisio captured from the commands,
file reads and data queries the agent really ran, not from what the model says. Shown in the web UI,
the terminal and
alisio run --proof(exit codes 0/10/11,proof/v1JSON). It does not prove the code is correct. See the Proof docs. - Typed plugin SDK: tools, commands, context, compaction and session hooks, provider-agnostic
completions and a storage port. Load plugins from a path or an npm package — install them
globally with
alisio install npm:<package>(or let the agent do it via the permissionedplugin_installtool). - Also: headless JSONL mode, MCP servers (with an optional persistent global
mcp.allowconsent that auto-connects enabled servers on every start, or per-session grants from the TUI), AGENTS.md scopes, Agent Skills, Herdr integration. - Runs on Node.js >= 22.16 or Bun; standalone binaries for Linux, macOS and Windows. The Pyodide
(
wasm) Python backend needs Node.js >= 22.22, >= 24.13 or >= 25.3.
Install
npm install -g @alisio/alisio-code # or: pnpm add -g @alisio/alisio-code · bun add -g @alisio/alisio-code
alisio # the CLI binary is installed as `alisio`
# Standalone binary (verifies the SHA-256 checksum):
curl -fsSL https://raw.githubusercontent.com/GustavoGutierrez/alisio/main/scripts/install.sh | sh
Quick start
alisio setup # writes .alisio/config.json without secrets
export DEEPSEEK_API_KEY='...' # keys come from the environment
alisio --config .alisio/config.json # TUI
alisio run "Explain this repository" --config .alisio/config.json --read-only
{
"provider": {
"baseURL": "https://api.deepseek.com/v1",
"apiKeyEnv": "DEEPSEEK_API_KEY",
"model": "deepseek-chat",
"streamUsage": true
}
}
Documentation
- English docs
- Documentación en español
- Product specification: the product direction, kept in the repository.
- Validation log and benchmark data: raw validation output.
The documentation site is bilingual (English and Spanish). The detailed implementation status (docs/implementation-status.md) is maintained in Spanish.
Packages
All packages are published under the alisio npm organization:
Dedicated model providers are independent plugins published from the
alisio-plugins monorepo and installed
separately: alisio install npm:@alisio/plugin-deepseek,
alisio install npm:@alisio/plugin-opencode, alisio install npm:@alisio/plugin-opencode-go.
Development
pnpm install --frozen-lockfile
pnpm dev # run the CLI from source (Bun)
pnpm check # typecheck, lint, tests, build, CLI e2e (Node and binary), packs, docs
pnpm publish -- --all --dry-run # preview the publishable packages; see docs/publishing.md
See CONTRIBUTING.md and Publishing.
Please read SECURITY.md before reporting a vulnerability, and follow CODE_OF_CONDUCT.md when participating.
License
MIT · Maintainer: Gustavo Gutiérrez
Third-party notice: Chart.js 4.5.1 (MIT, © Chart.js Contributors) is
bundled in @alisio/core for dashboard charts. Its copyright header stays in the bundled file and
its license text is kept in
packages/core/src/analysis/python/alisio_runtime/chart.LICENSE.txt.