Agentica: a multi-session CLI where each terminal is its own agent

The problem Agentica picks: one terminal, one agent, no way to split work

Most agent CLIs treat a session as a single conversation. You ask for something, it runs tools, it answers, and the context you built up is stranded in that window. If you have two unrelated jobs, you open two terminals and the two sessions know nothing about each other, even though they share a machine, a working directory and a model budget.

Agentica's answer is to make the session the unit of identity. The README describes three collaboration levels: an in-process task that spawns a temporary subagent, a process-level delegate that starts a whole separate agent for an independent job, and cross-terminal peer messages so two sessions can talk to each other. None of that requires a server, a broker or a deployment step, which is the part that distinguishes it from frameworks where multi-agent means a supervisor process you have to run somewhere.

The audience is narrow and specific. This is for someone who already works in a terminal, is comfortable with Python packaging, and wants the agents to share state on their own machine rather than in a hosted workspace. The README's own framing is a person plus a team of agents, and the desktop app, web UI and CLI all read the same ~/.agentica directory.

How the pieces fit: CLI, gateway and desktop share one state directory

The architecture visible in the repository splits into a Python package, a web front end and a desktop wrapper. The agentica package holds the runtime: models, tools, memory, skills. The gateway extra adds a FastAPI service that serves the compiled SPA and the IM channel integrations. The desktop directory holds an Electron app that renders the same web UI.

The state story is the clearest design decision. The Dockerfile sets AGENTICA_HOME=/data and HOME=/data, so the container keeps its configuration and caches in the named volume rather than in the image. The compose file mounts that volume as agentica-home and bind-mounts the current directory to /workspace. On a normal install the equivalent path is ~/.agentica. That means switching between the CLI and the browser does not fork your history or your model configuration, and the README states the desktop app uses the same ~/.agentica as the CLI.

The gateway is deliberately local. The compose file publishes 127.0.0.1:8881:8881, not 0.0.0.0, and sets GATEWAY_AUTH=false with a comment explaining that a generated web password is not allowed on a non-loopback bind. The comment also warns not to publish 0.0.0.0:8881 until a real password is set and GATEWAY_AUTH is true. That is a sensible default rather than a security feature, and it is worth reading as a boundary: the gateway is designed as a personal service, not a shared one.

Installing Agentica with uv tool and running the first session

The README installs both the CLI and the gateway through uv tool, which puts them in an isolated environment instead of binding to the system Python. If uv is not present, the documented bootstrap is a shell script, with a Homebrew alternative on macOS.

curl -LsSf https://astral.sh/uv/install.sh | sh
# macOS alternative: brew install uv

With uv available, the CLI is a single install command. The README notes that the command lives in ~/.local/bin on the script install path, and that uv tool update-shell fixes a missing command.

uv tool install agentica

Before the first real run you need a model provider. The README gives OpenAI-compatible variables and mentions ZAI_API_KEY as a free-to-start option, with precedence shell environment over .env over config.yaml. Writing them into ~/.agentica/.env is the documented persistent option, or you can let agentica setup generate ~/.agentica/config.yaml and switch models later with /model inside the CLI.

export OPENAI_BASE_URL="https://api.openai.com/v1"
export OPENAI_API_KEY="sk-xxx"

Then start the interactive terminal and type a request in natural language. The README's example is asking why a repository's unit tests are failing.

agentica

The Python SDK path is shorter if you want to script rather than chat. The README shows an Agent built from OpenAIChat with the built-in web search, file and execute tools, then a single run_sync call that searches for Python 3.13 features and writes them to features.md. DeepAgent() is the documented shortcut for the full set: built-in tools, compression, long-term memory, skills and MCP. Note that the README does not document a rollback or undo for file writes, so point work_dir at a scratch directory until you trust the tool configuration.

The gateway and IM channels: useful, but gated behind an unsigned build

Adding the web UI is one command with an extra. The README warns that if the CLI is already installed, the gateway install needs --force, and upgrades go through uv tool upgrade agentica.

uv tool install "agentica[gateway]"
agentica-gateway

The service listens on http://127.0.0.1:8881/chat. On first start it creates a default account and prints a random initial password to the terminal; an administrator can add accounts from a user management page, and the README states each account gets its own sessions and memory. The IM integrations cover WeChat, WeCom, Feishu and Telegram, with addressing by @session-name or by plain language handled by a gateway agent.

The desktop app is where the friction is. The README marks the current build as unsigned and documents the platform-specific workarounds: a sudo xattr -rd com.apple.quarantine /Applications/Agentica.app command on macOS, a SmartScreen bypass on Windows, and chmod +x on the AppImage for Linux. It also states that when no agentica-gateway is present, the desktop app installs a managed runtime with uv (Python 3.12 plus agentica[gateway]) into Application Support on first launch, kept outside ~/.agentica. An existing uv tool install or pip install is reused instead. That is a reasonable fallback, but it means first launch can download a Python runtime, and it is a behaviour you should test on a machine with a slow connection before rolling it out to anyone else.

Self-evolving skills and where the design gets thin

The self-evolution feature is the one that most needs scrutiny. The README says a completed run is compiled into a reusable SKILL.md that persists across sessions, so the next similar task reads the previous conclusion instead of starting over. The pyproject.toml dependency list includes python-frontmatter, which is consistent with Markdown files carrying YAML front matter, and the repository has an examples/self_evolution/ directory alongside examples/skills/. So the mechanism is plausible and the layout supports it.

What the README does not document is the failure mode that matters: how a stale or wrong SKILL.md is invalidated, whether skills are versioned, and what happens when two sessions write a skill for the same task class. No review step is described anywhere in the README or the pyproject.toml. If you adopt this, treat the skills directory as generated content that needs the same review as generated code, and check what the examples/self_evolution/ directory actually writes before enabling it on a repository you care about.

The benchmark claim deserves the same treatment. The README presents a comparison against OpenAI Codex on coding and data analysis question sets, with a headline of equal or better accuracy plus roughly half the wall clock and a third of the input tokens. The repository does include an evaluation/ directory and the README points to a benchmark page with reproduction commands and raw predictions.jsonl. That is more than most projects offer. It is still the maintainer's own harness, on public question sets, and the README does not describe how the prompt or tool surface was matched between the two systems. Reproduce it before quoting it.

Agentica against a general-purpose agent SDK

The closest comparison is a general-purpose Python agent framework such as LangChain, which the repository lists as a topic. The difference is where the product boundary sits. LangChain is a library you compose into an application you are building; it gives you abstractions and leaves the runtime, the terminal, the web UI and the storage layout to you. Agentica ships those as part of the package: the CLI is the entry point, the gateway is an extra, and ~/.agentica is the state contract.

That is a real trade. You get a working terminal agent after one install command and no application code. You also inherit the project's choices about session storage, config precedence and tool naming, and if you want a different memory backend or a different UI you are working against the grain rather than composing a library. For a team building a product on top of an agent, the library approach usually wins. For an individual who wants agents on their own machine this week, the product approach is the shorter path, and the multi-session peer messaging is the feature that has no obvious equivalent in the library-first tools.

A second comparison worth naming is the OpenAI Responses API, which the README lists as a supported provider alongside Chat Completions, DeepSeek, Claude, ZhipuAI, Qwen, Moonshot, Ollama and LiteLLM. If your work is already inside one vendor's API surface, the provider abstraction buys you less than the CLI does.

Licence, maintenance and the upgrade path you are signing up for

The licence is Apache-2.0, declared in pyproject.toml and in the LICENSE file, and the classifier is OSI Approved :: Apache Software License. That is a permissive licence with an explicit patent grant, and it imposes no copyleft obligation on your own code. It does not answer the questions that matter commercially: who owns the skills your agents generate, and whether the model providers you configure have terms compatible with the data you send them. The project says nothing about either, so those are your calls, not the project's.

Maintenance looks current rather than dormant. The last push was on 2026-09-10, and the release history shows v1.4.15 on 2026-09-01, v1.4.14 on 2026-08-25 and v1.4.13 on 2026-08-20. That is roughly a release every one to two weeks, which is a fast cadence for something you depend on. The practical cost is upgrade churn: the README already documents that adding the gateway to an existing CLI install needs --force, and the desktop app's managed runtime means a version skew between the app and a separately installed agentica-gateway is possible. Pin the version in your own environment and read CHANGELOG.md before running uv tool upgrade agentica on a machine where sessions matter.

Python support is broad, 3.10 through 3.14 per the classifiers, and the Dockerfile pins the runtime image to python:3.12-slim-bookworm. The container build compiles the web UI in a node:22-bookworm-slim stage and copies the output into agentica/gateway/ui, so the running container does not need Node. If you self-host, that is the path with the fewest moving parts.

Editorial conclusion

Adopt Agentica if you already live in a terminal and want the multi-session model, the built-in file and search tools, and a Python SDK that runs on Python 3.10 or newer. Do not adopt it if you need a signed desktop build, a single stable public API, or a hosted multi-tenant service: the desktop binaries are unsigned, the gateway binds to 127.0.0.1 by default, and the README shows a project still moving at a release-per-fortnight cadence. Before committing, run agentica setup, check what it writes into ~/.agentica/config.yaml, and read the benchmark page at shibing624.github.io/agentica/guides/benchmark to see whether the reproduction commands and predictions.jsonl match your own evaluation setup.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. shibing624/agentica on GitHub