Model or dataset
shibing624/agentica avatar
shibing624/agentica

Agentica: one agent per terminal session, and compression with no summary call

One person, a team of agents. Multi-session CLI that collaborates across terminals; /goal keeps long tasks running; WeChat/WeCom/Feishu gateway lets you call them back when you walk away. Async Python SDK, persistent memory, self-evolving skills.

364 stars49 forksPythonApache-2.0

At a glance

What is it?
Agentica is a Python agent SDK that ships as a CLI, a local web gateway and a desktop app over one shared home directory, and its two most distinctive mechanisms are a context compressor that never calls the model and a messenger gateway that lets you reach your own sessions from WeChat.
Who is it for?
Agentica fits a developer who wants agents to keep working across long sessions without paying for a summary on every compaction, and who is willing to give the gateway a shell, a file system and network access. It fits badly if you need a library with no opinions, because anthropic, Pillow, ruamel.yaml and prompt-toolkit all arrive as core dependencies rather than extras.
Can I use it commercially?
Yes. Apache-2.0 is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
Is it still maintained?
Yes. The repository received new commits within the last day.
What is it written in?
Mainly Python, according to GitHub's language statistics.

Answers come from the project's GitHub data, last synced on November 15, 2026, and from our analysis. They are not legal advice.

From daily snapshots

Star history

  • shibing624/agentica364 ★ · +12
Star history
Repository2026-09-132026-11-15
shibing624/agentica352364

12 Stars in the last 63 days, measured from the daily GitHub snapshot. Compare with other projects

Editorial analysis

Compression keeps a file path instead of a summary, and never calls the model

Most agent frameworks compact a long conversation by asking the model to summarize it, which costs an extra call and throws away detail. Agentica takes the opposite route and uses zero LLM summary. Oversized tool output is written to disk the moment it is produced, and only a 2000 character preview stays in context, split 40 percent head and 60 percent tail, plus the path to the full file. The model asks for more with `read_file` if it wants the detail. When the session has no file reading ability at all, the output is truncated and the truncation is explained, because emitting a path nobody can open would be worse than saying nothing. Eviction is deliberately lazy: it starts only once the window is more than 80 percent full, drops the oldest results first, and trims back to 50 percent, so an eviction cycle leaves half the window free. The placeholder that replaces an evicted call names which call it was, so the model can resend it verbatim, and the round currently in flight is never touched. Only a genuinely full window triggers a swap, where a `<context_window>` marker and handoff notes open an empty active window instead of inventing a summary turn. Originals stay in the session JSONL, `search_session` pulls any of it back by word, and the handoff is written to `<session>.notes.md`.

Three terminal verbs decide how far a piece of work travels

The unit of work is a session, and one session is one agent. Inside a session, `task` pulls a temporary subagent for work that belongs to the current turn. `delegate` is heavier: it starts a separate agent as its own process to go do an independent large job, and the session waits on the result rather than sharing a context with it. Peer messages carry the third case, letting two sessions on different terminals talk to each other directly, with no extra service to deploy for any of the three. The goal mechanism sits on top of that, keeping a long task running instead of waiting on the next prompt, which is why the project describes itself as one person and a team of agents. The SDK reaches the same territory from Python with `Agent.as_tool()`, Workflow, Swarm and a Markdown Subagent, and it adds an Actor-Critic pass where `refine()` runs several critics in parallel, a `SchemaCritic` that validates programmatically at no cost, an `AgentCritic` that gates on a different, stronger model, and automatic early stopping when it detects a loop.

The desktop build is unsigned, so three systems need a manual step

The desktop app is the same web UI in a window, reading the same `~/.agentica` as the CLI and the browser, but the current build carries no signature, and each operating system blocks it differently on first launch. On macOS the quarantine flag added to downloaded files makes an unsigned app report itself as damaged, and the documented fix removes the flag:

bash
sudo xattr -rd com.apple.quarantine /Applications/Agentica.app

On Windows, SmartScreen stops the installer and the path through is More information, then Run anyway, once. On Linux, an AppImage fetched by a browser arrives without the execute bit, so it does nothing when double-clicked:

bash
chmod +x agentica-desktop-linux-x86_64.AppImage

Packages installed through a package manager do not have that problem, according to the notes. If `agentica-gateway` is not on the machine, the app installs a managed runtime with uv on first open, Python 3.12 plus the gateway extra, into Application Support rather than into `~/.agentica`, and an existing uv or pip install is left alone. Running from source is also possible with `cd desktop && npm install && npm start`.

Configuration resolves shell first, then .env, then config.yaml

Pointing Agentica at a model is a matter of an API key, and the precedence is explicit: shell environment variables beat a `.env` file, which beats `config.yaml`. The shell route looks like this:

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

The same values can go into `~/.agentica/.env`, or `agentica setup` can generate `~/.agentica/config.yaml` for you, and inside the CLI the model can be switched at any time with `/model`. Installation follows the same isolation logic, since both the CLI and the gateway go in as uv tools rather than into system Python:

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

Adding the web extra on top of an existing CLI install needs `--force`, upgrades go through `uv tool upgrade agentica`, and a command that is not found after installing usually means the shell profile has not been updated, which `uv tool update-shell` fixes.

Experience is compiled into SKILL.md and read back next time

The self-evolution claim is a compilation step rather than a retrieval trick. After a run, what was learned is compiled into a `SKILL.md` that can be reused across sessions, so the next time a similar task arrives the agent reads its own earlier conclusion instead of starting from nothing. That sits next to the persistent memory system, which separates index from content, recalls on relevance, classifies into four types, and carries drift defense, with standing rules written into `AGENTS.md` so they survive a session boundary. The engine underneath is async-first: the API is natively async, parallel tool execution goes through `asyncio.gather()`, and a synchronous adapter is provided for callers who need one. Built-in tools cover `read_file`, `write_file`, `apply_patch`, `grep` and `glob`, plus `execute` and web search, and long reports are written out as HTML with `write_file` rather than returned inline. Guardrails run at input, output and tool level with detection during streaming, and the model list covers OpenAI Chat Completions and the Responses API, DeepSeek, Claude, ZhipuAI, Qwen, Moonshot, Ollama and LiteLLM.

The Docker profile turns auth off because the port is bound to loopback

Self-hosting runs `agentica-gateway` in a container, and the compose file is explicit about the trade it makes. The published port is `127.0.0.1:8881:8881`, the process inside listens on `0.0.0.0` so the mapping works, and `GATEWAY_AUTH` is set to false, with a comment giving the reason: a generated web password is not allowed on a non-loopback bind. The same comment warns not to publish 0.0.0.0:8881 until a real password is set and `GATEWAY_AUTH=true`. Outside Docker the behaviour is the opposite. The first start creates a `default` account and prints a random initial password into the terminal, an administrator can add more accounts from the user management page, and each account gets its own sessions and its own memory. State lives in a named volume mounted at `/data` with `AGENTICA_HOME` pointed at it, the working directory is bind-mounted to `/workspace`, and the `.env` file is optional rather than required. A healthcheck polls `/api/health` every 10 seconds with five retries and a 20 second start period.

The image compiles the web UI into the Python package

The Docker build has two stages and the interesting trick is where the front end ends up. A Node 22 stage installs the web dependencies with `npm ci`, copies the `web/` directory in, and runs the build, and a comment notes that the Vite configuration writes its output to `../agentica/gateway/ui`, which is a path inside the Python package rather than a separate static directory. The runtime stage is Python 3.12 on Debian slim, installs git and ca-certificates, creates `/data` and `/workspace`, copies the package plus the compiled UI out of the first stage, and installs the project with the gateway extra. The result is that the container needs no Node at runtime, and the same reasoning applies to pip and desktop users, who get the UI from the wheel. Two environment details matter for a bind-mounted workspace: `HOME` is set to `/data` alongside `AGENTICA_HOME`, and the working directory is `/workspace`, so whatever the container writes outside the project lands in the volume.

requirements.txt and pyproject.toml disagree on one dependency floor

Two dependency files ship in the root, and one of them says it should not exist. `requirements.txt` opens by stating that dependencies are declared in pyproject.toml, that it is kept for backward compatibility only, and that pyproject should be preferred. It then pins the runtime anyway, and pins one package differently: httpx is `>=0.24` there and `>=0.26` in pyproject, where the accompanying comment explains that the single-argument `AsyncClient(proxy=...)` form exists from 0.26 onward. The pyproject list runs to about twenty core dependencies and treats several as non-optional because the CLI is expected to work straight after install, which is why `anthropic` is there by default even though other providers are supported, alongside pydantic, Pillow for image encoding and format detection, tiktoken, pyyaml, ruamel.yaml, python-dotenv and python-frontmatter. Metadata requires Python 3.10 or newer and the classifiers run from 3.10 through 3.14, marked as production and stable. The repository also carries nineteen directories of examples, from `acp/` and `guardrails/` to `rag/`, `memory/`, `skills/` and `self_evolution/`, plus a separate TypeScript SDK under `sdk-ts/`.

Editorial conclusion

Agentica fits a developer who wants agents to keep working across long sessions without paying for a summary on every compaction, and who is willing to give the gateway a shell, a file system and network access. It fits badly if you need a library with no opinions, because anthropic, Pillow, ruamel.yaml and prompt-toolkit all arrive as core dependencies rather than extras. Three things to check first. The desktop build is unsigned, so macOS, Windows and Linux each need a one-time manual step before it will start. The Docker profile forces GATEWAY_AUTH off, which is only safe because the published port is bound to loopback, so do not publish 0.0.0.0:8881 until you have set a real password. And the README's headline benchmark, twice as fast with two thirds fewer input tokens than OpenAI Codex, is the project's own comparison; the reproduction commands and raw predictions.jsonl are published on its benchmark page, so read those rather than the summary. Apache-2.0 licensed, last pushed on 23 September 2026.

Frequently asked questions

What is agentica?

Agentica is a Python SDK for building AI agents, shipped as three front ends over one product: an interactive CLI called agentica, a local web UI served by agentica-gateway at 127.0.0.1:8881, and a desktop app. The three share the same history, working directory, model and configuration.

How does Agentica compress a long session?

Without calling the model. Oversized tool output is written to disk immediately and only a 2000 character preview plus a file path stays in context, eviction starts once the window passes 80 percent and trims the oldest results back to 50 percent, and a genuinely full window opens a new empty one with a context_window marker and handoff notes. Originals stay in the session JSONL and search_session can pull them back.

Can I use Agentica while I am away from the machine?

Yes, through WeChat, WeCom, Feishu or Telegram, which connect to the agent running on your own machine. You address a session directly with an @ mention of its name, or say what you want in plain words and let the gateway agent direct all the sessions on that machine.

Which models can Agentica use?

OpenAI Chat Completions and the Responses API, DeepSeek, Claude, ZhipuAI, Qwen, Moonshot, Ollama and LiteLLM are all named, and guardrails run at input, output and tool level with detection during streaming. The anthropic client is a core dependency, so it is installed whether or not you use it.

How do I install Agentica without touching system Python?

With uv tool. `uv tool install agentica` gives the CLI and `uv tool install "agentica[gateway]"` adds agentica-gateway for the web and desktop back ends, both in isolated environments. Adding the web extra over an existing CLI install needs `uv tool install --force "agentica[gateway]"`, and `uv tool upgrade agentica` upgrades it.

Official sources

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

If you maintain this project, the badge below links readers to this analysis and shows its maintenance status from the daily GitHub snapshot. Paste the markdown into your README; add ?metric=license or ?metric=stars to the image URL for a different field.

Add this badge to your README

markdown
[![Hysen Labs](https://hysenlabs.com/badge/shibing624-agentica.svg)](https://hysenlabs.com/projects/shibing624-agentica)

Star history chart for your README

markdown
[![Star history](https://hysenlabs.com/chart/shibing624-agentica.svg)](https://hysenlabs.com/projects/shibing624-agentica)

Was this useful?