Agentica
One person, a team of agents: a multi-session CLI where sessions collaborate, /goal keeps long tasks running, and WeChat/Feishu gateways call agents back when you walk away.
- Source repo
- shibing624/agentica
- Stars
- ★ 357
- Last updated
- today
- License
- Apache-2.0
- Primary language
- Python
- FA score
- 63/100 · Some gaps
At a glance
- How it runs
- Works with
- Universal · cross-platformOpenAI API · Claude API
- Cost
- Free software; you pay for model usage
- Setup effort
- Low · running in minutes
- You'll need
- Typical use
- A solo developer debugging failing unit tests or refactoring code in the terminal, using
taskfor read-only code search anddelegatefor independent heavy jobs - Not a fit if
- Users who want only official Claude or OpenAI models with no multi-vendor key setup
- Non-technical users unwilling to bypass unsigned desktop install warnings
- Source review
- 63/100 · Some gaps
What does this agent do, and when should you use it?
Agentica is an Apache-2.0 multi-agent framework and product by shibing624, pitched as "one person, a team of agents." Each terminal session is a collaborating agent: in-process task spawns read-only subagents, process-level delegate launches a full independent process for big jobs, and cross-terminal peer messaging lets sessions talk to each other — with nothing extra to deploy. Shipping surfaces include a CLI, a local Web UI via agentica-gateway, a Desktop App, an async Python SDK (Agent / DeepAgent), and a TypeScript client @agentica-ai/sdk. The core engine is an async-first Agentic Loop with built-in file/execute/search tools, two-layer context compaction, four-layer guardrails, persistent memory, and a self-evolving Skill system that compiles run experience into reusable SKILL.md files. It adapts to many providers — OpenAI, DeepSeek, Claude, Zhipu, Qwen, Ollama and more — and publishes a benchmark claiming roughly 2x speed and two-thirds fewer input tokens than OpenAI Codex on the same model, with reproducible commands and per-item metrics.
After running agentica, the agent reads and writes files (read_file/write_file/apply_patch/grep/glob), executes commands (execute), and performs web search to complete coding and data-analysis tasks. Multi-session collaboration works through three mechanisms: task (same-process read-only subagent), delegate (launches a full agentica --query --print process, managed via /ps, wait, /stop), and peer messaging (list_agents / send_message). /goal sustains long-running tasks; /cron schedules runs. Experience is automatically compiled into SKILL.md files reused across sessions. On the Python side, Agent(model=OpenAIChat(...), tools=[...]).run_sync(...) embeds agents in any code, while DeepAgent() gives the full stack (built-in tools + compaction + long-term memory + skills + MCP). agentica-gateway serves a local web app at http://127.0.0.1:8881/chat and bridges WeChat/WeCom/Feishu/Telegram, with per-account sessions and memory; Docker Compose supports self-hosting.
- A solo developer debugging failing unit tests or refactoring code in the terminal, using
taskfor read-only code search anddelegatefor independent heavy jobs - A Python engineer embedding
DeepAgentin their own codebase for one-line access to search, file writing, execution and long-term memory - An operator or researcher who steps away from the machine and drives local agents remotely via WeChat or Feishu with
@session-nameaddressing - A team wanting open models like DeepSeek instead of the Claude- or OpenAI-only lock-in of Claude Code/Codex, validating via the published benchmark
- Data or finance analysts using the examples' 6-agent financial research pipeline, RAG knowledge-base QA, and data pipelines
- Multi-device users sharing the same
~/.agenticahistory, config and workspace across CLI, browser and Desktop App
How do you install or deploy this agent?
Base install: pip install -U agentica (Python 3.10+). Web gateway: pip install -U "agentica[gateway]" then run agentica-gateway; first startup creates a default account and prints a random initial password to the terminal. Desktop builds ship as macOS dmg / Windows NSIS / Linux AppImage and deb (unsigned: on macOS run sudo xattr -rd com.apple.quarantine /Applications/Agentica.app; on Windows choose "Run anyway" in SmartScreen; on Linux run chmod +x on the AppImage). Self-hosting: cp .env.docker.example .env, fill in OPENAI_API_KEY, then docker compose up -d --build. TypeScript SDK: npm install @agentica-ai/sdk (the full scoped package name is required, not agentica-sdk).
How do you use this agent?
1) Set any provider's API key (priority: shell env > .env > config.yaml), e.g. export OPENAI_BASE_URL="https://api.openai.com/v1" and export OPENAI_API_KEY="sk-xxx", or the free-to-start export ZAI_API_KEY="your-api-key"; alternatively run agentica setup to generate ~/.agentica/config.yaml. 2) Type agentica in a terminal and chat directly; use /model to switch models, /goal for long tasks, /ps//stop to manage delegated processes, /cron for scheduled runs. 3) Python embedding: from agentica import Agent, OpenAIChat, BuiltinWebSearchTool, BuiltinFileTool, BuiltinExecuteTool, build the Agent, then call agent.run_sync("Search Python 3.13 features and write them to features.md"). 4) Open the web app at http://127.0.0.1:8881/chat; admins add accounts on the user-management page. 5) Node scripts against a running gateway: new Agentica({baseURL: "http://127.0.0.1:8881", apiKey: process.env.AGENTICA_GATEWAY_TOKEN}), then iterate agentica.chat.stream(...).
What are this agent's strengths and limitations?
- Cross-terminal multi-session collaboration (
task/delegate/peer) is absent from both Claude Code and Codex CLI and requires no extra deployment - No model lock-in: free provider switching with deep adaptation for open models like DeepSeek; the official benchmark reports ~2x speed and ~2/3 fewer input tokens than Codex on the same model
- Self-evolving skills: experience compiles into
SKILL.mdfiles reused across sessions, so similar tasks don't start from scratch - CLI, Web and Desktop share the same
~/.agenticastate, plus WeChat/WeCom/Feishu/Telegram gateways so you can drive agents remotely - Full async Python SDK, TypeScript SDK, MCP/ACP support and an extensive examples catalog make it embeddable in any codebase
- Young project (v1.4.x stage); its ecosystem and community are far smaller than Claude Code/Codex, so long-term maintenance risk needs evaluation
- Desktop builds are unsigned — macOS/Windows/Linux all require one-time manual workarounds, adding friction for non-technical users
- The performance claims come from the project's own benchmark (public coding and data-analysis suites); independent third-party validation evidence is limited
- IM gateway, Web and multi-account features require installing
agentica[gateway]and runningagentica-gatewaylocally; self-hosting means maintaining a Docker environment - The full feature chain (gateway, Desktop, managed runtime) involves Python 3.12/uv runtime details, making deployment more complex than a plain CLI
How does this agent compare with similar options?
The README compares Agentica with Claude Code and OpenAI Codex CLI: Agentica offers free multi-provider model switching, cross-terminal multi-session collaboration, Web/Desktop/IM entry points, self-evolving skills, a full Python SDK, and Apache-2.0 open source; Claude Code supports only Claude models and is closed source; Codex CLI supports only OpenAI models and lacks cross-terminal collaboration and self-evolving skills. The project's benchmark (same model, public question sets) claims accuracy no worse than Codex with lower wall-clock time and input tokens; reproducibility details are on its benchmark page.
Key facts side by side with the most closely related agents.
| Agent | Source review | Form / cost | Stars | Updated | Language | Full support on |
|---|---|---|---|---|---|---|
| Agentica This agent | 63 · Some gaps | CLIFree + model costs | ★ 357 | today | Python | OpenAI API · Claude API |
| ZhikunCode | 56 · Major gaps | Self-hosted serviceFree + model costs | ★ 528 | 7d ago | Java | OpenAI API · Claude API |
| Rovai AI | 49 · Major gaps | — | ★ 210 | today | Rust | Codex · Claude Code |
| Cotal | 77 · Good | CLIFree | ★ 349 | today | TypeScript | Codex · Claude Code |
How does FollowAgents rate this agent?
Why each dimension lost points
Evidence shows deliberate least-privilege design: read-only subagents by default, file tools narrowed to apply_patch/write_file, an ask permission profile, and layered guardrails; however, the actual permission-checking implementation is not visible in the provided files, so full marks are withheld. Deductions: sandboxing/confirmation details for high-impact external behaviors (execute tool, cron, IM gateways, desktop auto-installing a Python runtime) are not verifiable in the source; API keys rely on env/.env with no encryption or rotation guidance; no dependency audit or SBOM evidence; rollback rests only on asserted worktree/resume features. Attribution is clear (author XuMing, acknowledgements to phidata and openai-agents-python), but the publisher is unverified.
Self-consistency is good: README, pyproject (v1.4.15), News entries, and CLI/gateway entry points agree. Dependency availability benefits from fallback models, many providers, and an agentica doctor command. Deduction: actual failure message and recovery quality cannot be verified from source; only command names are visible.
Audience and scenarios (CLI/Web/Desktop/SDK/IM) are well described; the task/delegate/peer table draws capability boundaries; @session addressing, /goal, and /cron give precise triggers. Deductions: these are documentation assertions; cross-platform Python 3.10+ support is unverified by execution, and limits of self-evolving skills are not quantified.
Information architecture is the repo's strength: docs site, examples directory, installation troubleshooting FAQs (macOS quarantine, SmartScreen, AppImage permissions), bilingual docs; full Apache-2.0 license text; detailed per-release News and CHANGELOG link. Deductions: unsigned installer risk is left to manual user workarounds rather than mitigation; maintenance rests on a single individual (bus factor 1).
Output usability is supported by trace views, /export JSONL, and streaming. If true, the claimed same-model speed/token advantages over Codex represent real marginal value. Deduction: performance and cost-benefit claims are self-run benchmarks (self-published predictions.l), unverifiable in static review; the 'two-thirds fewer tokens' figure has no independent corroboration.
Key claims link to benchmark pages and per-release notes, giving reasonable traceability. Deductions: all benchmark and comparison data are single-source (author self-run) with no third-party replication; the README mixes promotional assertions ('all coding problems correct') with factual statements without fact/inference separation.
- Desktop installers are unsigned and the README instructs users to bypass macOS Gatekeeper and Windows SmartScreen; verify installer hashes and provenance before deploying in controlled environments.
- BuiltinExecuteTool and delegate processes have full local execution capability, and IM gateways (WeChat/WeCom/Feishu/Telegram) inject external messages into agents; enable the ask permission profile by default and restrict which sessions/directories gateway accounts can reach.
- All benchmark comparisons are author self-run; reproduce the evaluation independently before accepting the performance and token-saving claims.
- The project depends heavily on a single maintainer and iterates rapidly (releases every few days); pin a specific version for production and watch the CHANGELOG for breaking changes.
- This was a static review with no code executed; actual behavior of permissions, guardrails, and failure recovery is unverified at runtime.
Recent releases
Latest entries from the project's GitHub Releases. Notes are quoted from upstream as written, not rewritten or tested by FollowAgents.
-
Release notes excerpt
Agentica v1.5.0 Langfuse 5 每次用户请求一条 Trace：根 Observation 是 AGENT，每次真实模型请求（含 retry/fallback）是子 GENERATION，每次真实工具执行是子 TOOL。Hook 不上报。历史默认重放整个窗口（num_history_turns 默认 None，旧 tool 结果不再每轮截成 2000 字符）。换模型保留工具历史；一轮内跨 provider fallback 能带着本轮工具结果完成。长会话按 provider 实测的 prompt 大小校准压缩水位。 破坏性变更： num_history_turns 默认 None；truncate_tool_results 默认 False。删除 Model.supports_replayed_tool_history 与 Layer 2「先催模型写 notes、推迟换窗」。OpenAIChat.langfuse_trace_name 删除，agentica[langfuse] 最低版本为 5.0.4。 安装： uv tool install agentica==1.5.0（网页/桌面：uv tool install "agentica[gateway]==1.5.0"） …View on GitHub ↗ -
Release notes excerpt
Agentica v1.4.17 输出上限按用户配置 > 模型目录 > 网关默认，不再吃网关默认的小上限。网关返回空的 200 会原样重发，连续空回复记为 empty_response；max_tokens 下始终写不完的回答记为 output_truncated，不再当成完整结果。内置 analyze_image，模型可以自己看图。API 错误按状态码和异常类型决定同模型重试还是切 fallback。 破坏性变更： 公开 from agentica import Agent 等不变，子模块路径按领域收进子包。worktree 不再搬家、不上锁、不销毁占坑目录。settings.hooks 改为具名多消费者 consumers[]。 论文：[When Self-Evolution Backfires: Pre-Commit Gating against Skill Contamination in LLM Agents](https://arxiv.org/abs/2608.05810)（arXiv:2608.05810）。 安装： pip install -U agentica==1.4.17（网页/桌面：pip install -U "agentica[gateway]"） …View on GitHub ↗ -
Release notes excerpt
Agentica v1.4.16 Layer 2 compact 改为空窗换窗（不再调用 LLM 或 /responses/compact 做摘要）。旧对话留在 session JSONL，用 search_session 查；交接写旁边的 <session>.notes.md。交互 CLI 新增可选 attach（往正在跑的会话里注入用户消息）和外部 hooks（settings.hooks，默认关）。MCP extra 只支持 2.x。 安装： pip install -U agentica==1.4.16（网页/桌面：pip install -U "agentica[gateway]"） TypeScript： npm install @agentica-ai/[email protected] 自托管： docker compose up -d --build 下载桌面版 桌面安装包由 CI 稍后挂到本 Release。安装包未签名，首次启动被系统拦下时按 [README](https://github.com/shibing624/agentica#desktop-app) 解锁一次即可。 …View on GitHub ↗
FAQ
Which model provider is required? Can it start for free?
Does my data leave my machine?
~/.agentica, and self-hosting uses Docker with named volumes. However, inference still calls your chosen provider's API unless you use a local model via Ollama.When should I use task, delegate or peer messaging?
task for short read-only work (code search, lookups); delegate for big jobs needing independent context or another directory (managed via /ps, wait, /stop); peer messaging only to sync information between two interactive sessions.The Desktop App won't open — what now?
sudo xattr -rd com.apple.quarantine /Applications/Agentica.app; on Windows click "More info → Run anyway" in SmartScreen; on Linux run chmod +x on the AppImage. You can also run from source: cd desktop && npm install && npm start.How do I connect WeChat or Feishu?
agentica[gateway] and run agentica-gateway; then WeChat/WeCom/Feishu/Telegram can reach your local agents directly, addressed with @session-name or routed by the gateway agent across all sessions. See the project's Gateway documentation.