{"id":50766442,"url":"https://github.com/mf2023/encre","last_synced_at":"2026-06-11T14:01:29.282Z","repository":{"id":363329783,"uuid":"1255074191","full_name":"mf2023/Encre","owner":"mf2023","description":"Encre — A Python agent framework, a Rust native core, and an Electron desktop app, all developed together in one repository. Backend-agnostic and multi-provider, with streaming tool calls, a permission/safety engine, persistent memory, multi-agent orchestration, a desktop UI, a CLI runner, a WebSocket server, and 18 platform adapters.","archived":false,"fork":false,"pushed_at":"2026-06-08T11:43:59.000Z","size":8175,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"master","last_synced_at":"2026-06-08T13:25:24.079Z","etag":null,"topics":["agent-framework","ai-agents","anthropic","function-calling","hermes-agent","llm","mcp","multi-agent","ollama","openai","openclaw","python","rust","tool-use"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mf2023.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"docs/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"docs/SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2026-05-31T11:22:24.000Z","updated_at":"2026-06-08T11:48:56.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/mf2023/Encre","commit_stats":null,"previous_names":["mf2023/encre"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/mf2023/Encre","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mf2023%2FEncre","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mf2023%2FEncre/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mf2023%2FEncre/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mf2023%2FEncre/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mf2023","download_url":"https://codeload.github.com/mf2023/Encre/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mf2023%2FEncre/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34201842,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-11T02:00:06.485Z","response_time":57,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent-framework","ai-agents","anthropic","function-calling","hermes-agent","llm","mcp","multi-agent","ollama","openai","openclaw","python","rust","tool-use"],"created_at":"2026-06-11T14:01:27.154Z","updated_at":"2026-06-11T14:01:29.240Z","avatar_url":"https://github.com/mf2023.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cdiv align=\"center\"\u003e\n\n# Encre\n\nEnglish | [简体中文](README.zh.md)\n\n[Documentation](https://dunimd.github.io/encre) | [Changelog](docs/CHANGELOG.md) | [Security](docs/SECURITY.md) | [Contributing](docs/CONTRIBUTING.md) | [Code of Conduct](docs/CODE_OF_CONDUCT.md)\n\n\u003ca href=\"https://github.com/mf2023/Encre\" target=\"_blank\"\u003e\n    \u003cimg alt=\"GitHub\" src=\"https://img.shields.io/badge/GitHub-encre-181717?style=flat-square\u0026logo=github\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://gitee.com/dunimd/encre\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Gitee\" src=\"https://img.shields.io/badge/Gitee-encre-C71D23?style=flat-square\u0026logo=gitee\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://x.com/Dunimd2025\" target=\"_blank\"\u003e\n    \u003cimg alt=\"X\" src=\"https://img.shields.io/badge/X-Dunimd-000000?style=flat-square\u0026logo=x\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://space.bilibili.com/3493284091529457\" target=\"_blank\"\u003e\n    \u003cimg alt=\"BiliBili\" src=\"https://img.shields.io/badge/BiliBili-Dunimd-00A1D6?style=flat-square\u0026logo=bilibili\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://huggingface.co/dunimd\" target=\"_blank\"\u003e\n    \u003cimg alt=\"Hugging Face\" src=\"https://img.shields.io/badge/Hugging%20Face-Dunimd-FFD21E?style=flat-square\u0026logo=huggingface\"/\u003e\n\u003c/a\u003e\n\u003ca href=\"https://modelscope.cn/organization/dunimd\" target=\"_blank\"\u003e\n    \u003cimg alt=\"ModelScope\" src=\"https://img.shields.io/badge/ModelScope-Dunimd-1E6CFF?style=flat-square\u0026logo=data:image/svg+xml;base64,PHN2ZyB3aWR0aD0iMTQiIGhlaWdodD0iMTQiIHZpZXdCb3g9IjAgMCAxNCAxNCIgZmlsbD0ibm9uZSIgeG1sbnM9Imh0dHA6Ly93d3cudzMub3JnLzIwMDAvc3ZnIj4KPHBhdGggZD0iTTcuMDA2IDBDMy4xNDIgMCAwIDMuMTQyIDAgNy4wMDZTMy4xNDIgMTQuMDEyIDcuMDA2IDE0LjAxMkMxMC44NyAxNC4wMTIgMTQuMDEyIDEwLjg3IDE0LjAxMiA3LjAwNkMxNC4wMTIgMy4xNDIgMTAuODcgMCA3LjAwNiAwWiIgZmlsbD0iIzFFNkNGRiIvPgo8L3N2Zz4K\"/\u003e\n\u003c/a\u003e\n\n\u003ca href=\"https://www.apache.org/licenses/LICENSE-2.0\" target=\"_blank\"\u003e\n    \u003cimg alt=\"License\" src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg?style=flat-square\"/\u003e\n\u003c/a\u003e\n\n**Encre** — A Python agent framework, a Rust native core, and an Electron desktop app, all developed together in one repository. Backend-agnostic and multi-provider, with streaming tool calls, a permission/safety engine, persistent memory, multi-agent orchestration, a desktop UI, a CLI runner, a WebSocket server, and 18 platform adapters.\n\n\u003c/div\u003e\n\n\u003ch2 align=\"center\"\u003e🏗️ Core Architecture\u003c/h2\u003e\n\n### Multi-Language Architecture\nEncre uses a multi-language architecture with three major components, letting each layer use the most appropriate language for its domain:\n\n\u003cdiv align=\"center\"\u003e\n\n| Language | Component | Purpose |\n|:---------|:----------|:--------|\n| **Python** | `backend/encre/` | AI Agent framework core — agent loop, 31 LLM backends, 36 built-in tools, 18 adapters, safety engine, memory, skills, swarm, hooks, LSP, MCP |\n| **Rust** | `native/crates/encre-core` | Native high-performance library — file I/O, regex search, glob, diff, sandbox, tokenizer, BM25 indexer, Landlock, SIMD search, LSP protocol, semantic embeddings |\n| **Rust** | `native/crates/encre-py` | PyO3 bindings exposing the Rust core to Python as `encre._native` |\n| **TypeScript** | `desktop/` | Encre Desktop — Electron-based desktop app with React UI, Monaco Editor, xterm.js terminal, IPC bridge to the Python backend |\n\n\u003c/div\u003e\n\nEncre is shipped as a single repository with three components that share the same release cycle. There is no standalone library or separately installable package — clone the whole repository to use Encre.\n\n### Repository Structure\n\n```\nd:\\encre/\n├── pyproject.toml             # Python build \u0026 dependencies (builds backend/encre/)\n├── build.py                   # One-shot build script (Rust + Python + Desktop)\n├── gen.py                     # Icon / asset generator\n├── package-lock.json          # Root node lockfile (mirrors desktop)\n├── LICENSE                    # Apache 2.0 license\n├── README.md / README.zh.md   # This document\n│\n├── backend/                   # Python agent framework\n│   ├── encre/                 #   The `encre` Python package\n│   │   ├── __init__.py        #   Public API surface\n│   │   ├── agent.py           #   EncreAgent — public Agent class\n│   │   ├── loop.py            #   EncreLoop — execution loop\n│   │   ├── session.py         #   EncreSession — conversation state\n│   │   ├── safety.py          #   EncreSafetyEngine — 6 permission modes\n│   │   ├── autosafety.py      #   EncreAutoSafetyClassifier\n│   │   ├── config.py          #   Configuration management\n│   │   ├── crypto.py          #   AES-GCM encryption helpers\n│   │   ├── ssrf.py            #   EncreSSRFGuard (DNS + CIDR blocklists)\n│   │   ├── ratelimit.py       #   EncreRateLimiter\n│   │   ├── rollback.py        #   Git-based rollback (EncreRollbackGit)\n│   │   ├── recovery.py        #   Error recovery engine\n│   │   ├── scheduler.py       #   EncreScheduler (cron-style jobs)\n│   │   ├── goal.py            #   Goal runner + evaluator loop\n│   │   ├── telemetry.py       #   EncreTelemetry (turns, tools, retries)\n│   │   ├── native.py          #   Python wrapper over encre._native\n│   │   ├── _native.pyi        #   Type stubs for the Rust extension\n│   │   ├── backend.py         #   create_backend() factory\n│   │   ├── dangerous_commands.txt  # Bash safety patterns\n│   │   ├── backends/          #   31 LLM provider adapters\n│   │   ├── adapters/          #   18 platform adapters (chat platforms)\n│   │   ├── agents/            #   Built-in sub-agent definitions\n│   │   ├── channels/          #   Transport: websocket, terminal, HTTP, slash\n│   │   ├── tools/             #   36 built-in tools + tool registry + MCP\n│   │   ├── hooks/             #   EncreHookSystem\n│   │   ├── memdir/            #   Persistent memory system (frontmatter)\n│   │   ├── skills/            #   Skill registry + 11 bundled skills\n│   │   ├── swarm/             #   Multi-agent system (teammate/mailbox/...)\n│   │   ├── task/              #   Task manager \u0026 executor\n│   │   ├── server/            #   WebSocket server + admin HTTP API\n│   │   ├── gateway/           #   Gateway client/server protocol\n│   │   ├── compact/           #   Context compaction (9 strategies)\n│   │   ├── lsp/               #   LSP client + multi-server manager\n│   │   ├── codebase/          #   Code indexer (BM25 + dependency graph)\n│   │   ├── computer/          #   Desktop \u0026 browser automation\n│   │   ├── evolution/         #   Meta-cognition, reflex, strategy optimizer\n│   │   ├── feedback/          #   Error-correction learner\n│   │   ├── notebook/          #   Interactive Python kernel session\n│   │   ├── plugins/           #   Plugin registry \u0026 manifest types\n│   │   ├── profile/           #   User profile inference\n│   │   ├── soul/              #   Soul system files (persona/memory)\n│   │   ├── spec/              #   Spec document engine\n│   │   ├── prompts/           #   Prompt blocks, skills, safety, goals\n│   │   ├── sandbox/           #   Docker container sandbox\n│   │   ├── search/            #   MCP-backed web search\n│   │   ├── learning/          #   Skill generation + consolidation\n│   │   ├── rules/             #   Rules loader\n│   │   ├── thinking/          #   Thinking config resolution\n│   │   ├── iclaw/             #   iClaw CLI (automation runner)\n│   │   ├── git/               #   Git repository \u0026 diff utilities\n│   │   └── utils/             #   ID generation, token counting, types\n│   └── tests/                 # Pytest suite (configured via pyproject.toml)\n│       ├── conftest.py\n│       ├── test_agent.py\n│       ├── test_backends.py\n│       ├── test_backend_*.py\n│       ├── test_safety.py\n│       ├── test_session.py\n│       ├── test_loop.py\n│       ├── test_native.py\n│       └── ...                #   40+ test modules\n│\n├── native/                    # Rust workspace\n│   ├── Cargo.toml             #   Workspace root\n│   └── crates/\n│       ├── encre-core/        #   Native core (package name: `encre`)\n│       │   ├── Cargo.toml\n│       │   └── src/\n│       │       ├── lib.rs\n│       │       ├── fs.rs          # Native read/write\n│       │       ├── search.rs      # Regex search, glob\n│       │       ├── simd_search.rs # SIMD-accelerated matching\n│       │       ├── diff.rs        # Unified diff + apply\n│       │       ├── shell.rs       # Sandboxed shell execution\n│       │       ├── sandbox.rs     # Sandbox result types\n│       │       ├── landlock.rs    # Linux Landlock enforcement\n│       │       ├── tokenizer.rs   # Heuristic token counter\n│       │       ├── embedding.rs   # Cosine / Jaccard similarity\n│       │       ├── indexer.rs     # BM25 code search index\n│       │       └── lsp_proto.rs   # LSP JSON-RPC parser/builder\n│       └── encre-py/          # PyO3 bindings → `encre._native`\n│           ├── Cargo.toml\n│           └── src/lib.rs\n│\n├── desktop/                   # Electron desktop application\n│   ├── main.ts                #   Electron main process\n│   ├── preload.ts             #   Context bridge (IPC)\n│   ├── build.js               #   esbuild configuration\n│   ├── package.json           #   Node.js dependencies \u0026 scripts\n│   ├── electron-builder.yml   #   NSIS / pkg / deb packaging\n│   ├── tsconfig.json          #   TypeScript config (main process)\n│   ├── fetch_icons.js         #   Icon fetcher\n│   └── renderer/              #   Frontend (React 19)\n│       ├── index.html\n│       ├── styles.css\n│       ├── design-system.css\n│       ├── xterm.css\n│       ├── bundle.js          #   esbuild output\n│       ├── tsconfig.json\n│       ├── assets/            #   Logos \u0026 icons\n│       ├── src/               #   TypeScript sources\n│       │   ├── app.ts\n│       │   ├── chat.ts\n│       │   ├── session.ts\n│       │   ├── session_inner.ts\n│       │   ├── settings.ts\n│       │   ├── state.ts\n│       │   ├── stream.ts\n│       │   ├── ws.ts\n│       │   ├── search.ts\n│       │   ├── i18n.ts\n│       │   ├── iclaw.ts\n│       │   ├── agents.ts\n│       │   ├── automation.ts\n│       │   ├── tools.ts\n│       │   ├── files.ts\n│       │   ├── workspace.ts\n│       │   ├── viewmanager.ts\n│       │   ├── permissions.ts\n│       │   ├── dialog.ts\n│       │   ├── notifications.ts\n│       │   ├── slash_commands.ts\n│       │   ├── icons.ts\n│       │   ├── crypto.ts       #   Renderer-side AES helpers\n│       │   ├── easter-egg.ts\n│       │   ├── transition-helper.ts\n│       │   ├── types.ts\n│       │   ├── global.d.ts\n│       │   └── locales/        #   en.ts / zh.ts\n│       └── vs/                 #   Monaco Editor (bundled)\n│\n├── docs/                      # Project documentation\n│   ├── CHANGELOG.md\n│   ├── CODE_OF_CONDUCT.md\n│   ├── CONTENT_GUIDELINES.md\n│   ├── CONTRIBUTING.md\n│   ├── DATA_PROCESSING_RULES.md\n│   ├── MINORS_PRIVACY.md\n│   ├── PLAN.md\n│   ├── PRIVACY.md\n│   ├── PRIVACY_CN.md\n│   ├── SECURITY.md\n│   ├── TERMS.md\n│   ├── TERMS_CN.md\n│   ├── THANKS.md\n│   ├── THANKS_CN.md\n│   └── USER_AGREEMENT.md\n│\n└── .github/\n    └── workflows/\n        └── build-binary.yml   # CI: builds release binaries\n```\n\n\u003ch2 align=\"center\"\u003e🚀 Key Features\u003c/h2\u003e\n\n#### 🧠 Multi-Provider LLM Backends (31)\n- **First-party**: OpenAI, Anthropic Claude, DeepSeek, Google Gemini, Groq, Ollama, Local (HuggingFace transformers)\n- **Chinese \u0026 regional**: Alibaba (Qwen / DashScope), Tencent, Xiaomi MiMo, Kimi (Moonshot), GLM (Zhipu / Z.ai), MiniMax\n- **Aggregators / routers**: OpenRouter, AI Gateway, OpenCode, Kilocode, Arcee, Novita\n- **Cloud \u0026 enterprise**: AWS Bedrock, GitHub Copilot\n- **Self-hosted \u0026 compatible**: LM Studio, OpenAI Compatible, OpenAI SSE\n- **Meta-backends**: Failover (multi-backend health failover), Router (cost / task routing), Retry (transparent retry)\n- **Catalog**: MCP Catalog, native model catalog (`encre.backends.catalog`)\n- Unified streaming interface, automatic thinking-block resolution, OpenAI-compatible chat completions\n\n#### 🤖 Built-in Sub-Agents (9)\n- **General mode**: `coder`, `researcher`, `critic`\n- **Workspace mode**: `architect`, `planner`\n- **Plan / Spec mode**: `spec-writer`\n- **iClaw (auto) mode**: `monitor`, `executor`, `scheduler`\n- Each sub-agent is defined as a `SubAgentConfig` and loaded from `encre/agents/builtin.py` with prompt templates under `encre/prompts/skills/`.\n\n#### 🛠️ Built-in Tools (36)\n- **File**: `file_read`, `file_write`, `file_edit`, `apply_patch`, `find_tool`, `glob`, `grep`, `pdf`, `spreadsheet`\n- **Shell \u0026 execution**: `bash`, `bash_io` (background, output, kill, list), `docker`, `deploy`, `agent` (spawn a sub-agent)\n- **Web**: `web_fetch`, `web_search` (MCP-backed), `browser` (Playwright automation)\n- **Development**: `lsp` (LSP diagnostics/hover), `notebook` (IPython kernel), `database`\n- **Task system**: `task_create`, `task_get`, `task_list`, `task_update`, `task_output`, `task_stop`\n- **Scheduling \u0026 memory**: `cron_create`, `cron_delete`, `cron_list`, `todo`, `memory`\n- **Desktop \u0026 media**: `desktop` (pyautogui / mss / uiautomation), `image` (Pillow / OCR)\n- **Integrations**: `git`, `rest_client`\n- **External protocol**: MCP client (`encre.tools.mcp` + `MCPManager`) for Model Context Protocol servers\n\n#### 🌐 Platform Adapters (18)\nChat-platform adapters turn external messages (Telegram, Discord, Slack, …) into a normalized channel. Concretely:\n- Discord, Slack, Telegram, **DingTalk**, Email (IMAP+SMTP), **Feishu / Lark**\n- **WeCom** (企业微信), **Weixin** (微信), **WhatsApp**, **Signal**, **SMS**\n- **Matrix**, **MS Graph** (Microsoft 365), **Home Assistant**, **QQ Bot**, **BlueBubbles** (iMessage)\n- **Yuanbao** (腾讯元宝), **Webhook** (generic incoming webhook)\n- Each adapter implements `BaseAdapter` and is registered through `encre.adapters.manager`.\n\n#### 🔒 Safety \u0026 Permission Engine\n- **6 permission modes**: `bypass` (no checks), `dont_ask` (auto-allow), `accept_edits` (auto-allow edits), `plan` (plan first), `auto` (heuristic), `default` (ask for confirmation)\n- **Bash command analyzer** with dangerous-pattern detection (`encre.safety.analyze_bash_command`, `dangerous_commands.txt`)\n- **SSRF guard** combining DNS resolution with CIDR blocklists (`encre.ssrf.EncreSSRFGuard`)\n- **Docker container sandbox** (`encre.sandbox.container.EncreContainerSandbox`) with seccomp-style isolation\n- **Rust-level sandbox** (`encre-core/sandbox.rs`) with Linux **Landlock** enforcement (`landlock.rs`)\n- **Auto safety classifier** (`encre.autosafety.EncreAutoSafetyClassifier`) — AI-based permission decisions\n- **Rate limiter** (`encre.ratelimit.EncreRateLimiter`) for backends and tool calls\n\n#### 💾 Persistent Memory (`encre.memdir`)\n- Frontmatter-parsed Markdown files stored in a `memdir/` directory\n- `MEMORY.md` entrypoint index with **aging / freshness tracking** (`memdir/age.py`, `memdir/manifest.py`)\n- **Semantic search** powered by NumPy similarity (`memdir/semantic.py`)\n- Working memory + consolidation actions\n- Goal/memory prompt templates under `prompts/memdir/`\n\n#### 🎯 Skill System (11 bundled)\n- `debug`, `loop`, `batch`, `verify`, `stuck`, `code_review`, `refactor`, `gen_test`, `web_research`, `data_viz`, `write_docs`\n- **Priority-based override**: managed \u003e user \u003e project \u003e bundled\n- **Dynamic system-prompt generation** via `encre.prompts.system.EncrePromptBuilder`\n- Skill generator + consolidator (`encre.learning`) for runtime skill creation\n\n#### 🤝 Multi-Agent Orchestration\n- **Swarm**: `EncreTeammate`, `EncreSwarmManager` (concurrency-limited), `EncreMailbox` (async mailbox)\n- **Orchestrator**: `EncreOrchestrator`, `EncreBlackboard` (shared state), `EncreConsensus` (proposal/vote), `AgentRole` / `RoleRegistry`\n- **Task planner**: `EncreTaskPlanner` produces a `TaskTree` of `TaskNode`s\n- **Task system**: typed CRUD with bash / agent / workflow executors (`encre.task`)\n\n#### 🧱 Native Rust Core (`native/crates/encre-core`)\n- **Fast file I/O** (`fs.rs`) — native read/write with offset/limit\n- **Regex search \u0026 glob** (`search.rs`)\n- **SIMD-accelerated matching** (`simd_search.rs`) — `simd_contains`, `simd_find_all`, `simd_memmem`\n- **Unified diff** (`diff.rs`) — `compute_diff` / `apply_diff`\n- **Sandboxed shell execution** (`shell.rs` + `sandbox.rs`) with Landlock\n- **Linux Landlock** (`landlock.rs`) — read-only filesystem, no-network, full sandbox\n- **Heuristic token counter** (`tokenizer.rs`) — English / CJK / digit / code heuristics\n- **Semantic similarity** (`embedding.rs`) — cosine and Jaccard text similarity\n- **BM25 indexer** (`indexer.rs`) — `Bm25Index` exposed to Python\n- **LSP protocol** (`lsp_proto.rs`) — JSON-RPC 2.0 parser, diagnostics, content-length helpers\n- Optional features: `embedding` (Candle + tokenizers), `simd` (`wide`), `landlock` (Linux only)\n\n#### 🖥️ Encre Desktop (Electron + React 19)\n- Full-featured AI chat UI with Markdown rendering (`markdown-it`), code highlighting (`highlight.js`), and file attachments\n- **Multi-session** chat with branching and search\n- **Settings**: model config, gateway, agent, MCP servers, skills, rules, memory, code index, agents\n- **iClaw mode** — automation runner with batch operations\n- **Embedded terminal** (`xterm.js` + `node-pty`) with a working directory browser\n- **Code editor** — Monaco Editor (16+ language workers bundled, including TS, JS, Python, Rust, Go, Java, C/C++/C#, PHP, Ruby, Swift, Kotlin, SQL, etc.)\n- **i18n** — `en.ts` / `zh.ts` locales, runtime language switching\n- **System tray** + notifications + voice input support\n- **Encrypted browser cookie store** — AES-256-GCM (key file in user data dir)\n- **Git integration** — status / diff with 5-second cache and in-flight diff tracking\n- **Multi-target packaging**: NSIS (Windows x64), `pkg` (macOS x64 + arm64), `deb` / `rpm` (Linux x64)\n\n#### 🛠️ Developer Toolchain\n- **Context compaction** (`encre.compact`) — 9 strategies: Always, Auto, TokenBudget, BudgetReduction, Semantic, Snip, MicroCompact, ContextCollapse, MultiStagePipeline\n- **Semantic compact** — `SemanticToolOutputCompactor`, `ContextPartitioner` with tiered context\n- **LSP client** — 16+ language servers auto-discovered on `PATH` (Python, TypeScript, JavaScript, Rust, Go, Java, C#, C++, PHP, Ruby, Swift, Kotlin, CSS, HTML, JSON, YAML, …)\n- **Codebase indexer** — BM25 search + dependency graph (`encre.codebase`)\n- **Evolution** — meta-cognition, reflex loop, strategy optimizer, error/learner\n- **Feedback learner** — Jaccard similarity-based error correction\n- **Interactive notebook** — IPython kernel session\n- **Plugin system** — `EncrePlugin` / `PluginManifest` / `PluginRegistry`\n- **Profile inference** + **Soul system** for user persona\n- **Spec engine** — `SpecDocument` / `SpecSection` / `EncreSpecEngine`\n- **Goal system** + **Scheduler** + **Telemetry**\n- **WebSocket server** + admin HTTP API + session manager\n- **CLI runner** — `python -m encre.iclaw` (iClaw mode)\n- **Gateway protocol** — `GatewayServer` / `GatewayClient`\n\n\u003ch2 align=\"center\"\u003e🔧 Development Setup\u003c/h2\u003e\n\n### Prerequisites\n- **Python**: 3.11+ (the `encre` package requires `\u003e=3.11`)\n- **Node.js**: 18+ (Electron 42, recommended 20+ for the desktop app)\n- **Rust**: 1.65+ (stable, optional — only needed if you want to rebuild the native extension)\n- **Platforms**: Linux (x64, arm64), macOS (x64, arm64), Windows (x64)\n\n### Clone \u0026 Setup\n\n```bash\n# 1. Clone the repository\ngit clone https://github.com/mf2023/Encre.git\ncd encre\n\n# 2. (Recommended) one-shot build — Rust extension + Python wheel + Desktop bundle\npython build.py\n\n# 3. --- Python Agent Framework ---\n\n# Install core dependencies in editable mode (uses pyproject.toml)\npip install -e .\n\n# Install with development dependencies (pytest, ruff, mypy, pre-commit)\npip install -e \".[dev]\"\n\n# Install optional backends / adapters as needed\npip install -e \".[anthropic]\"       # Anthropic Claude backend\npip install -e \".[ollama]\"          # Ollama local backend\npip install -e \".[discord]\"         # Discord adapter\npip install -e \".[slack]\"           # Slack adapter\npip install -e \".[telegram]\"        # Telegram adapter\npip install -e \".[dingtalk]\"        # DingTalk adapter\npip install -e \".[email]\"           # Email adapter (IMAP + SMTP)\npip install -e \".[local]\"           # Local model backend (PyTorch + transformers)\npip install -e \".[aws]\"             # AWS Bedrock backend (boto3)\npip install -e \".[aiohttp]\"         # aiohttp HTTP utilities\npip install -e \".[native]\"          # Pre-built native extension (encre-native)\n\n# Install every extra (anthropic, ollama, native, aiohttp, discord, slack,\n# telegram, dingtalk, email, local, aws) in one go\npip install -e \".[all]\"\n\n# 4. --- Desktop Application ---\n\ncd desktop\nnpm install\ncd ..\n\n# Playwright browsers (for the `browser` tool)\nplaywright install\n```\n\n### Build Commands\n\n```bash\n# One-shot: builds the Rust extension, copies _native into backend/encre/,\n#            installs the Python package, and bundles the desktop renderer.\npython build.py\n\n# Or build each component by hand:\n\n# Python: build a wheel\npip install build\npython -m build\n\n# Rust: build the native extension (release)\ncd native\ncargo build --release -p encre-py\n# The compiled _native.pyd / _native.so is then copied into backend/encre/\n# (the build.py script does this automatically)\n\n# Desktop: bundle TypeScript and launch Electron\ncd desktop\nnpm run build         # esbuild → dist/main.js, dist/preload.js, renderer/bundle.js\nnpm start             # build + launch Electron\nnpm run dist          # build + electron-builder (NSIS / pkg / deb / rpm)\ncd ..\n```\n\n### Run Tests \u0026 Quality\n\n```bash\n# Python tests (pytest is configured via pyproject.toml: testpaths = [\"backend/tests\"])\npytest -v\npytest backend/tests/test_agent.py -v\npytest backend/tests/test_backends.py -v\n\n# Lint \u0026 type check\nruff check .\nmypy backend/encre\n\n# Desktop type check (main process + renderer)\ncd desktop\nnpm run typecheck\n```\n\n\u003ch2 align=\"center\"\u003e⚡ Quick Start\u003c/h2\u003e\n\n### Basic Agent (Python API)\n\n```python\nimport asyncio\nfrom encre import EncreAgent\n\nasync def main():\n    agent = EncreAgent(\n        backend=\"openai\",\n        model=\"gpt-4o\",\n        api_key=\"...\",\n    )\n\n    async for event in agent.run(\"Write a Python script that recursively lists all .py files\"):\n        if event.type == \"text\":\n            print(event.content, end=\"\")\n        elif event.type == \"tool_result\":\n            print(f\"\\n[Tool: {event.tool_name}] → {event.result[:100]}...\")\n        elif event.type == \"finish\":\n            print(f\"\\n\\nDone. Reason: {event.reason}\")\n\nasyncio.run(main())\n```\n\n### With Tool Permission / Safety\n\n```python\nfrom encre import EncreAgent\n\nagent = EncreAgent(\n    backend=\"anthropic\",\n    model=\"claude-sonnet-4-20250514\",\n    api_key=\"...\",\n    tool_permission_mode=\"auto\",   # one of: bypass / dont_ask / accept_edits / plan / auto / default\n)\n```\n\n### Multi-Provider Switch\n\n```python\nfrom encre import EncreAgent\n\nfor provider, model, key in [\n    (\"openai\", \"gpt-4o\", OPENAI_KEY),\n    (\"anthropic\", \"claude-sonnet-4-20250514\", ANTHROPIC_KEY),\n    (\"google\", \"gemini-2.5-pro\", GOOGLE_KEY),\n]:\n    agent = EncreAgent(backend=provider, model=model, api_key=key)\n    async for event in agent.run(\"Explain Rust ownership in one sentence\"):\n        if event.type == \"text\":\n            print(event.content, end=\"\")\n    print(\"\\n\" + \"=\" * 40)\n```\n\n### CLI: iClaw Mode\n\n```bash\n# iClaw is a long-running automation runner (encre/iclaw/__main__.py)\npython -m encre.iclaw --help\n```\n\n### MCP Servers\n\n```python\nfrom encre.tools.mcp_manager import MCPManager, bootstrap_mcp_servers\n\n# Bootstrap MCP servers from the user's default config path\nmanager = MCPManager()\nawait bootstrap_mcp_servers(manager)\n```\n\n\u003ch2 align=\"center\"\u003e🖥️ Desktop Application\u003c/h2\u003e\n\nEncre Desktop is an Electron + React 19 AI chat application:\n\n- **Chat**: Markdown rendering (`markdown-it`), syntax highlighting (`highlight.js`), file attachments\n- **Sessions**: Multiple concurrent sessions, branching, fuzzy search (`fuse.js`)\n- **Settings**: Model config, gateway, agent, MCP servers, skills, rules, memory, code index, agents\n- **iClaw Mode**: Automation runner with batch operations\n- **Terminal**: Embedded terminal (`xterm.js` + `node-pty`)\n- **Editor**: Monaco Editor with 16+ language workers (TypeScript, JavaScript, Python, Rust, Go, Java, C/C++/C#, PHP, Ruby, Swift, Kotlin, SQL, …)\n- **i18n**: English (`en.ts`) and Chinese (`zh.ts`) localization, runtime switching\n- **Git integration**: status / diff with 5-second cache, in-flight diff tracking\n- **System tray + notifications**\n- **Encrypted browser cookie store** (AES-256-GCM, key in user data dir)\n\n**Launch:**\n\n```bash\ncd desktop\nnpm start\n```\n\n**Package for distribution:**\n\n```bash\ncd desktop\nnpm run dist\n# → Windows: NSIS installer (x64)\n# → macOS:   .pkg (x64 + arm64)\n# → Linux:   .deb and .rpm (x64)\n```\n\n\u003ch2 align=\"center\"\u003e🔧 Configuration\u003c/h2\u003e\n\n### Configuration Example\n\n```yaml\n# config.yaml\nbackend: \"openai\"\nmodel: \"gpt-4o\"\napi_key: \"${OPENAI_API_KEY}\"\n\nsafety:\n  tool_permission_mode: \"auto\"   # bypass / dont_ask / accept_edits / plan / auto / default\n\nmemory:\n  enabled: true\n  max_tokens: 4096\n\ncompact:\n  strategy: \"auto\"               # one of the 9 encre.compact strategies\n  threshold_tokens: 32000\n\ntools:\n  enabled:\n    - file_read\n    - file_write\n    - bash\n    - web_fetch\n    - web_search\n  disabled:\n    - browser\n    - notebook\n```\n\n### Configuration Sources (priority low → high)\n\n1. Built-in defaults (`encre.config.EncreConfig`)\n2. Configuration files (YAML, TOML)\n3. Environment variables (prefixed with `ENCRE_`)\n4. Programmatic configuration passed to `EncreAgent(...)`\n\n\u003ch2 align=\"center\"\u003e❓ Frequently Asked Questions\u003c/h2\u003e\n\n**Q: How many LLM backends does Encre support?**\nA: **31** backends: OpenAI, Anthropic, DeepSeek, Google Gemini, Groq, Ollama, Local (HuggingFace), Alibaba (Qwen / DashScope), Tencent, Xiaomi, Kimi, GLM, MiniMax, Arcee, Novita, OpenRouter, AWS Bedrock, GitHub Copilot, LM Studio, OpenAI Compatible, OpenAI SSE, AI Gateway, Kilocode, OpenCode, plus the meta-backends Failover, Router, Retry, and the MCP Catalog and the static `encre.backends.catalog` provider catalog.\n\n**Q: How many built-in tools ship with Encre?**\nA: **36** built-in tools under `encre/tools/builtin/`, plus a fully pluggable tool registry and an MCP client for external tools.\n\n**Q: How do I add a custom tool?**\nA: Subclass `EncreTool` (defined in `encre/tools/base.py`), implement `execute(**kwargs) -\u003e str` and the formatting methods, then register the tool with the `ToolRegistry` (or use the discovery mechanism in `encre/tools/discovery.py`).\n\n**Q: What are the permission / safety modes?**\nA: **6** modes: `bypass` (no checks), `dont_ask` (auto-allow), `accept_edits` (auto-allow edits), `plan` (plan first), `auto` (heuristic), `default` (ask for confirmation). They are surfaced through `encre.utils.types.PermissionMode`.\n\n**Q: Is this a PyPI library I can `pip install`?**\nA: No. Encre is shipped as a single repository containing Python, Rust, and Electron/TypeScript code; the three components share a single release cycle. To use it, clone the repository and follow the Development Setup guide. The Python package can then be installed from source via `pip install -e .`.\n\n**Q: How does the memory system work?**\nA: Memory is stored as frontmatter-parsed `.md` files in a `memdir/` directory with a `MEMORY.md` index (`encre.memdir`). The system tracks freshness/age, automatically prunes aged entries, and exposes semantic search backed by NumPy similarity.\n\n**Q: Does Encre support multi-agent workflows?**\nA: Yes. The **Swarm** system (`encre.swarm`) provides teammates, a concurrency-limited swarm manager, an async mailbox, an orchestrator, a blackboard, and a consensus protocol. The **Task** system (`encre.task`) provides typed CRUD with bash / agent / workflow executors. There are also **9 built-in sub-agents** defined in `encre/agents/builtin.py` (coder, researcher, critic, architect, planner, spec-writer, monitor, executor, scheduler).\n\n**Q: How does Encre use Rust?**\nA: Performance-critical operations — file I/O, regex search, glob, unified diff, SIMD pattern matching, BM25 indexing, sandbox / Landlock, token counting, semantic similarity, and the LSP JSON-RPC parser — are implemented in Rust (`native/crates/encre-core`) and exposed to Python through PyO3 (`encre._native`). The extension is built with `python build.py` or `cargo build --release -p encre-py`.\n\n**Q: How do I build the desktop app for distribution?**\nA: Run `npm run dist` in the `desktop/` directory. `electron-builder` produces NSIS installers (Windows x64), `.pkg` packages (macOS x64 + arm64), and `.deb` / `.rpm` packages (Linux x64). Output goes to `desktop/release/`.\n\n**Q: Where do the chat-platform adapters live?**\nA: Under `encre/adapters/` — 18 adapters implementing `BaseAdapter`, including Discord, Slack, Telegram, DingTalk, Feishu, WeCom, Weixin, WhatsApp, Signal, SMS, Email, Matrix, MS Graph, Home Assistant, QQ Bot, BlueBubbles, Yuanbao, and a generic Webhook adapter.\n\n**Q: How do I run Encre as a server?**\nA: `encre.server` exposes a WebSocket server and an admin HTTP API. Use `EncreServer` / `run_server` from `encre.server.app` (lazy-loaded from `encre/__init__.py`) and the `SessionManager` from `encre.server.session_manager`.\n\n\u003ch2 align=\"center\"\u003e🌏 Community \u0026 License\u003c/h2\u003e\n\n- Issues and PRs are welcome!\n- GitHub: https://github.com/mf2023/Encre\n- Gitee: https://gitee.com/dunimd/encre\n- GitCode: https://gitcode.com/dunimd/encre\n\n\u003cdiv align=\"center\"\u003e\n\n## 📄 License \u0026 Open Source Agreements\n\n### 🏛️ Project License\n\n\u003cp align=\"center\"\u003e\n  \u003ca href=\"LICENSE\"\u003e\n    \u003cimg src=\"https://img.shields.io/badge/License-Apache%202.0-blue.svg\" alt=\"Apache License 2.0\"\u003e\n  \u003c/a\u003e\n\u003c/p\u003e\n\nThis project uses **Apache License 2.0**. See [LICENSE](LICENSE) for the full text.\n\n### 📋 Dependency Licenses\n\nThe dependency license list below reflects the packages used by the **Python framework**, the **Rust core**, and the **Electron desktop app**. Versions and exact license texts are not pinned here; consult each upstream project for the authoritative license.\n\n\u003cdiv align=\"center\"\u003e\n\n| 📦 Package | 📜 License | 📦 Package | 📜 License |\n|:-----------|:-----------|:-----------|:-----------|\n| httpx | BSD-3-Clause | pydantic | MIT |\n| beautifulsoup4 | MIT | markdownify | MIT |\n| lxml | BSD-3-Clause | tomli | MIT |\n| tomli-w | MIT | pyyaml | MIT |\n| cryptography | Apache-2.0 / BSD | zero-api-key-web-search | Apache-2.0 |\n| pathspec | MPL-2.0 | websockets | BSD-3-Clause |\n| Pillow | Historical | playwright | Apache-2.0 |\n| tiktoken | MIT | numpy | BSD-3-Clause |\n| loguru | MIT | openai | Apache-2.0 |\n| anthropic | MIT | google-generativeai | Apache-2.0 |\n| ollama | MIT | groq | MIT |\n| aiohttp | Apache-2.0 | discord.py | MIT |\n| slack_bolt | MIT | slack_sdk | MIT |\n| python-telegram-bot | GPL-3.0 | dingtalk-stream | MIT |\n| aioimaplib | BSD-3-Clause | aiosmtplib | MIT |\n| torch | BSD-3-Clause | transformers | Apache-2.0 |\n| boto3 | Apache-2.0 | pytest | MIT |\n| pytest-asyncio | Apache-2.0 | ruff | MIT |\n| mypy | MIT | pre-commit | MIT |\n| mss | MIT | openpyxl | MIT |\n| pdfplumber | MIT | pyautogui | BSD-3-Clause |\n| pypdf | BSD-3-Clause | PyPDF2 | BSD-3-Clause |\n| pytesseract | Apache-2.0 | uiautomation | MIT |\n| watchfiles | MIT | | |\n| serde | MIT/Apache-2.0 | serde_json | MIT/Apache-2.0 |\n| regex | MIT/Apache-2.0 | walkdir | MIT/Apache-2.0 |\n| similar | MIT | glob | MIT/Apache-2.0 |\n| tempfile | MIT/Apache-2.0 | candle-core | Apache-2.0 |\n| tokenizers | Apache-2.0 | wide | MIT/Apache-2.0 |\n| pyo3 | MIT/Apache-2.0 | | |\n| electron | MIT | electron-builder | MIT |\n| esbuild | MIT | typescript | Apache-2.0 |\n| @xterm/xterm | MIT | @xterm/addon-fit | MIT |\n| @xterm/addon-webgl | MIT | node-pty | MIT |\n| markdown-it | MIT | highlight.js | BSD-3-Clause |\n| fuse.js | Apache-2.0 | monaco-editor | MIT |\n| react | MIT | react-dom | MIT |\n| simple-icons | CC0-1.0 | | |\n\n\u003c/div\u003e\n\n\u003c/div\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmf2023%2Fencre","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmf2023%2Fencre","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmf2023%2Fencre/lists"}