Encre

English | 简体中文

Documentation | Changelog | Security | Contributing | Code of Conduct

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.

🏗️ Core Architecture

Multi-Language Architecture

Encre uses a multi-language architecture with three major components, letting each layer use the most appropriate language for its domain:

Language	Component	Purpose
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
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
Rust	`native/crates/encre-py`	PyO3 bindings exposing the Rust core to Python as `encre._native`
TypeScript	`desktop/`	Encre Desktop — Electron-based desktop app with React UI, Monaco Editor, xterm.js terminal, IPC bridge to the Python backend

Encre 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.

Repository Structure

d:\encre/
├── pyproject.toml             # Python build & dependencies (builds backend/encre/)
├── build.py                   # One-shot build script (Rust + Python + Desktop)
├── gen.py                     # Icon / asset generator
├── package-lock.json          # Root node lockfile (mirrors desktop)
├── LICENSE                    # Apache 2.0 license
├── README.md / README.zh.md   # This document
│
├── backend/                   # Python agent framework
│   ├── encre/                 #   The `encre` Python package
│   │   ├── __init__.py        #   Public API surface
│   │   ├── agent.py           #   EncreAgent — public Agent class
│   │   ├── loop.py            #   EncreLoop — execution loop
│   │   ├── session.py         #   EncreSession — conversation state
│   │   ├── safety.py          #   EncreSafetyEngine — 6 permission modes
│   │   ├── autosafety.py      #   EncreAutoSafetyClassifier
│   │   ├── config.py          #   Configuration management
│   │   ├── crypto.py          #   AES-GCM encryption helpers
│   │   ├── ssrf.py            #   EncreSSRFGuard (DNS + CIDR blocklists)
│   │   ├── ratelimit.py       #   EncreRateLimiter
│   │   ├── rollback.py        #   Git-based rollback (EncreRollbackGit)
│   │   ├── recovery.py        #   Error recovery engine
│   │   ├── scheduler.py       #   EncreScheduler (cron-style jobs)
│   │   ├── goal.py            #   Goal runner + evaluator loop
│   │   ├── telemetry.py       #   EncreTelemetry (turns, tools, retries)
│   │   ├── native.py          #   Python wrapper over encre._native
│   │   ├── _native.pyi        #   Type stubs for the Rust extension
│   │   ├── backend.py         #   create_backend() factory
│   │   ├── dangerous_commands.txt  # Bash safety patterns
│   │   ├── backends/          #   31 LLM provider adapters
│   │   ├── adapters/          #   18 platform adapters (chat platforms)
│   │   ├── agents/            #   Built-in sub-agent definitions
│   │   ├── channels/          #   Transport: websocket, terminal, HTTP, slash
│   │   ├── tools/             #   36 built-in tools + tool registry + MCP
│   │   ├── hooks/             #   EncreHookSystem
│   │   ├── memdir/            #   Persistent memory system (frontmatter)
│   │   ├── skills/            #   Skill registry + 11 bundled skills
│   │   ├── swarm/             #   Multi-agent system (teammate/mailbox/...)
│   │   ├── task/              #   Task manager & executor
│   │   ├── server/            #   WebSocket server + admin HTTP API
│   │   ├── gateway/           #   Gateway client/server protocol
│   │   ├── compact/           #   Context compaction (9 strategies)
│   │   ├── lsp/               #   LSP client + multi-server manager
│   │   ├── codebase/          #   Code indexer (BM25 + dependency graph)
│   │   ├── computer/          #   Desktop & browser automation
│   │   ├── evolution/         #   Meta-cognition, reflex, strategy optimizer
│   │   ├── feedback/          #   Error-correction learner
│   │   ├── notebook/          #   Interactive Python kernel session
│   │   ├── plugins/           #   Plugin registry & manifest types
│   │   ├── profile/           #   User profile inference
│   │   ├── soul/              #   Soul system files (persona/memory)
│   │   ├── spec/              #   Spec document engine
│   │   ├── prompts/           #   Prompt blocks, skills, safety, goals
│   │   ├── sandbox/           #   Docker container sandbox
│   │   ├── search/            #   MCP-backed web search
│   │   ├── learning/          #   Skill generation + consolidation
│   │   ├── rules/             #   Rules loader
│   │   ├── thinking/          #   Thinking config resolution
│   │   ├── iclaw/             #   iClaw CLI (automation runner)
│   │   ├── git/               #   Git repository & diff utilities
│   │   └── utils/             #   ID generation, token counting, types
│   └── tests/                 # Pytest suite (configured via pyproject.toml)
│       ├── conftest.py
│       ├── test_agent.py
│       ├── test_backends.py
│       ├── test_backend_*.py
│       ├── test_safety.py
│       ├── test_session.py
│       ├── test_loop.py
│       ├── test_native.py
│       └── ...                #   40+ test modules
│
├── native/                    # Rust workspace
│   ├── Cargo.toml             #   Workspace root
│   └── crates/
│       ├── encre-core/        #   Native core (package name: `encre`)
│       │   ├── Cargo.toml
│       │   └── src/
│       │       ├── lib.rs
│       │       ├── fs.rs          # Native read/write
│       │       ├── search.rs      # Regex search, glob
│       │       ├── simd_search.rs # SIMD-accelerated matching
│       │       ├── diff.rs        # Unified diff + apply
│       │       ├── shell.rs       # Sandboxed shell execution
│       │       ├── sandbox.rs     # Sandbox result types
│       │       ├── landlock.rs    # Linux Landlock enforcement
│       │       ├── tokenizer.rs   # Heuristic token counter
│       │       ├── embedding.rs   # Cosine / Jaccard similarity
│       │       ├── indexer.rs     # BM25 code search index
│       │       └── lsp_proto.rs   # LSP JSON-RPC parser/builder
│       └── encre-py/          # PyO3 bindings → `encre._native`
│           ├── Cargo.toml
│           └── src/lib.rs
│
├── desktop/                   # Electron desktop application
│   ├── main.ts                #   Electron main process
│   ├── preload.ts             #   Context bridge (IPC)
│   ├── build.js               #   esbuild configuration
│   ├── package.json           #   Node.js dependencies & scripts
│   ├── electron-builder.yml   #   NSIS / pkg / deb packaging
│   ├── tsconfig.json          #   TypeScript config (main process)
│   ├── fetch_icons.js         #   Icon fetcher
│   └── renderer/              #   Frontend (React 19)
│       ├── index.html
│       ├── styles.css
│       ├── design-system.css
│       ├── xterm.css
│       ├── bundle.js          #   esbuild output
│       ├── tsconfig.json
│       ├── assets/            #   Logos & icons
│       ├── src/               #   TypeScript sources
│       │   ├── app.ts
│       │   ├── chat.ts
│       │   ├── session.ts
│       │   ├── session_inner.ts
│       │   ├── settings.ts
│       │   ├── state.ts
│       │   ├── stream.ts
│       │   ├── ws.ts
│       │   ├── search.ts
│       │   ├── i18n.ts
│       │   ├── iclaw.ts
│       │   ├── agents.ts
│       │   ├── automation.ts
│       │   ├── tools.ts
│       │   ├── files.ts
│       │   ├── workspace.ts
│       │   ├── viewmanager.ts
│       │   ├── permissions.ts
│       │   ├── dialog.ts
│       │   ├── notifications.ts
│       │   ├── slash_commands.ts
│       │   ├── icons.ts
│       │   ├── crypto.ts       #   Renderer-side AES helpers
│       │   ├── easter-egg.ts
│       │   ├── transition-helper.ts
│       │   ├── types.ts
│       │   ├── global.d.ts
│       │   └── locales/        #   en.ts / zh.ts
│       └── vs/                 #   Monaco Editor (bundled)
│
├── docs/                      # Project documentation
│   ├── CHANGELOG.md
│   ├── CODE_OF_CONDUCT.md
│   ├── CONTENT_GUIDELINES.md
│   ├── CONTRIBUTING.md
│   ├── DATA_PROCESSING_RULES.md
│   ├── MINORS_PRIVACY.md
│   ├── PLAN.md
│   ├── PRIVACY.md
│   ├── PRIVACY_CN.md
│   ├── SECURITY.md
│   ├── TERMS.md
│   ├── TERMS_CN.md
│   ├── THANKS.md
│   ├── THANKS_CN.md
│   └── USER_AGREEMENT.md
│
└── .github/
    └── workflows/
        └── build-binary.yml   # CI: builds release binaries

🚀 Key Features

🧠 Multi-Provider LLM Backends (31)

First-party: OpenAI, Anthropic Claude, DeepSeek, Google Gemini, Groq, Ollama, Local (HuggingFace transformers)
Chinese & regional: Alibaba (Qwen / DashScope), Tencent, Xiaomi MiMo, Kimi (Moonshot), GLM (Zhipu / Z.ai), MiniMax
Aggregators / routers: OpenRouter, AI Gateway, OpenCode, Kilocode, Arcee, Novita
Cloud & enterprise: AWS Bedrock, GitHub Copilot
Self-hosted & compatible: LM Studio, OpenAI Compatible, OpenAI SSE
Meta-backends: Failover (multi-backend health failover), Router (cost / task routing), Retry (transparent retry)
Catalog: MCP Catalog, native model catalog (encre.backends.catalog)
Unified streaming interface, automatic thinking-block resolution, OpenAI-compatible chat completions

🤖 Built-in Sub-Agents (9)

General mode: coder, researcher, critic
Workspace mode: architect, planner
Plan / Spec mode: spec-writer
iClaw (auto) mode: monitor, executor, scheduler
Each sub-agent is defined as a SubAgentConfig and loaded from encre/agents/builtin.py with prompt templates under encre/prompts/skills/.

🛠️ Built-in Tools (36)

File: file_read, file_write, file_edit, apply_patch, find_tool, glob, grep, pdf, spreadsheet
Shell & execution: bash, bash_io (background, output, kill, list), docker, deploy, agent (spawn a sub-agent)
Web: web_fetch, web_search (MCP-backed), browser (Playwright automation)
Development: lsp (LSP diagnostics/hover), notebook (IPython kernel), database
Task system: task_create, task_get, task_list, task_update, task_output, task_stop
Scheduling & memory: cron_create, cron_delete, cron_list, todo, memory
Desktop & media: desktop (pyautogui / mss / uiautomation), image (Pillow / OCR)
Integrations: git, rest_client
External protocol: MCP client (encre.tools.mcp + MCPManager) for Model Context Protocol servers

🌐 Platform Adapters (18)

Chat-platform adapters turn external messages (Telegram, Discord, Slack, …) into a normalized channel. Concretely:

Discord, Slack, Telegram, DingTalk, Email (IMAP+SMTP), Feishu / Lark
WeCom (企业微信), Weixin (微信), WhatsApp, Signal, SMS
Matrix, MS Graph (Microsoft 365), Home Assistant, QQ Bot, BlueBubbles (iMessage)
Yuanbao (腾讯元宝), Webhook (generic incoming webhook)
Each adapter implements BaseAdapter and is registered through encre.adapters.manager.

🔒 Safety & Permission Engine

6 permission modes: bypass (no checks), dont_ask (auto-allow), accept_edits (auto-allow edits), plan (plan first), auto (heuristic), default (ask for confirmation)
Bash command analyzer with dangerous-pattern detection (encre.safety.analyze_bash_command, dangerous_commands.txt)
SSRF guard combining DNS resolution with CIDR blocklists (encre.ssrf.EncreSSRFGuard)
Docker container sandbox (encre.sandbox.container.EncreContainerSandbox) with seccomp-style isolation
Rust-level sandbox (encre-core/sandbox.rs) with Linux Landlock enforcement (landlock.rs)
Auto safety classifier (encre.autosafety.EncreAutoSafetyClassifier) — AI-based permission decisions
Rate limiter (encre.ratelimit.EncreRateLimiter) for backends and tool calls

💾 Persistent Memory (`encre.memdir`)

Frontmatter-parsed Markdown files stored in a memdir/ directory
MEMORY.md entrypoint index with aging / freshness tracking (memdir/age.py, memdir/manifest.py)
Semantic search powered by NumPy similarity (memdir/semantic.py)
Working memory + consolidation actions
Goal/memory prompt templates under prompts/memdir/

🎯 Skill System (11 bundled)

debug, loop, batch, verify, stuck, code_review, refactor, gen_test, web_research, data_viz, write_docs
Priority-based override: managed > user > project > bundled
Dynamic system-prompt generation via encre.prompts.system.EncrePromptBuilder
Skill generator + consolidator (encre.learning) for runtime skill creation

🤝 Multi-Agent Orchestration

Swarm: EncreTeammate, EncreSwarmManager (concurrency-limited), EncreMailbox (async mailbox)
Orchestrator: EncreOrchestrator, EncreBlackboard (shared state), EncreConsensus (proposal/vote), AgentRole / RoleRegistry
Task planner: EncreTaskPlanner produces a TaskTree of TaskNodes
Task system: typed CRUD with bash / agent / workflow executors (encre.task)

🧱 Native Rust Core (`native/crates/encre-core`)

Fast file I/O (fs.rs) — native read/write with offset/limit
Regex search & glob (search.rs)
SIMD-accelerated matching (simd_search.rs) — simd_contains, simd_find_all, simd_memmem
Unified diff (diff.rs) — compute_diff / apply_diff
Sandboxed shell execution (shell.rs + sandbox.rs) with Landlock
Linux Landlock (landlock.rs) — read-only filesystem, no-network, full sandbox
Heuristic token counter (tokenizer.rs) — English / CJK / digit / code heuristics
Semantic similarity (embedding.rs) — cosine and Jaccard text similarity
BM25 indexer (indexer.rs) — Bm25Index exposed to Python
LSP protocol (lsp_proto.rs) — JSON-RPC 2.0 parser, diagnostics, content-length helpers
Optional features: embedding (Candle + tokenizers), simd (wide), landlock (Linux only)

🖥️ Encre Desktop (Electron + React 19)

Full-featured AI chat UI with Markdown rendering (markdown-it), code highlighting (highlight.js), and file attachments
Multi-session chat with branching and search
Settings: model config, gateway, agent, MCP servers, skills, rules, memory, code index, agents
iClaw mode — automation runner with batch operations
Embedded terminal (xterm.js + node-pty) with a working directory browser
Code editor — Monaco Editor (16+ language workers bundled, including TS, JS, Python, Rust, Go, Java, C/C++/C#, PHP, Ruby, Swift, Kotlin, SQL, etc.)
i18n — en.ts / zh.ts locales, runtime language switching
System tray + notifications + voice input support
Encrypted browser cookie store — AES-256-GCM (key file in user data dir)
Git integration — status / diff with 5-second cache and in-flight diff tracking
Multi-target packaging: NSIS (Windows x64), pkg (macOS x64 + arm64), deb / rpm (Linux x64)

🛠️ Developer Toolchain

Context compaction (encre.compact) — 9 strategies: Always, Auto, TokenBudget, BudgetReduction, Semantic, Snip, MicroCompact, ContextCollapse, MultiStagePipeline
Semantic compact — SemanticToolOutputCompactor, ContextPartitioner with tiered context
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, …)
Codebase indexer — BM25 search + dependency graph (encre.codebase)
Evolution — meta-cognition, reflex loop, strategy optimizer, error/learner
Feedback learner — Jaccard similarity-based error correction
Interactive notebook — IPython kernel session
Plugin system — EncrePlugin / PluginManifest / PluginRegistry
Profile inference + Soul system for user persona
Spec engine — SpecDocument / SpecSection / EncreSpecEngine
Goal system + Scheduler + Telemetry
WebSocket server + admin HTTP API + session manager
CLI runner — python -m encre.iclaw (iClaw mode)
Gateway protocol — GatewayServer / GatewayClient

🔧 Development Setup

Prerequisites

Python: 3.11+ (the encre package requires >=3.11)
Node.js: 18+ (Electron 42, recommended 20+ for the desktop app)
Rust: 1.65+ (stable, optional — only needed if you want to rebuild the native extension)
Platforms: Linux (x64, arm64), macOS (x64, arm64), Windows (x64)

Clone & Setup

# 1. Clone the repository
git clone https://github.com/mf2023/Encre.git
cd encre

# 2. (Recommended) one-shot build — Rust extension + Python wheel + Desktop bundle
python build.py

# 3. --- Python Agent Framework ---

# Install core dependencies in editable mode (uses pyproject.toml)
pip install -e .

# Install with development dependencies (pytest, ruff, mypy, pre-commit)
pip install -e ".[dev]"

# Install optional backends / adapters as needed
pip install -e ".[anthropic]"       # Anthropic Claude backend
pip install -e ".[ollama]"          # Ollama local backend
pip install -e ".[discord]"         # Discord adapter
pip install -e ".[slack]"           # Slack adapter
pip install -e ".[telegram]"        # Telegram adapter
pip install -e ".[dingtalk]"        # DingTalk adapter
pip install -e ".[email]"           # Email adapter (IMAP + SMTP)
pip install -e ".[local]"           # Local model backend (PyTorch + transformers)
pip install -e ".[aws]"             # AWS Bedrock backend (boto3)
pip install -e ".[aiohttp]"         # aiohttp HTTP utilities
pip install -e ".[native]"          # Pre-built native extension (encre-native)

# Install every extra (anthropic, ollama, native, aiohttp, discord, slack,
# telegram, dingtalk, email, local, aws) in one go
pip install -e ".[all]"

# 4. --- Desktop Application ---

cd desktop
npm install
cd ..

# Playwright browsers (for the `browser` tool)
playwright install

Build Commands

# One-shot: builds the Rust extension, copies _native into backend/encre/,
#            installs the Python package, and bundles the desktop renderer.
python build.py

# Or build each component by hand:

# Python: build a wheel
pip install build
python -m build

# Rust: build the native extension (release)
cd native
cargo build --release -p encre-py
# The compiled _native.pyd / _native.so is then copied into backend/encre/
# (the build.py script does this automatically)

# Desktop: bundle TypeScript and launch Electron
cd desktop
npm run build         # esbuild → dist/main.js, dist/preload.js, renderer/bundle.js
npm start             # build + launch Electron
npm run dist          # build + electron-builder (NSIS / pkg / deb / rpm)
cd ..

Run Tests & Quality

# Python tests (pytest is configured via pyproject.toml: testpaths = ["backend/tests"])
pytest -v
pytest backend/tests/test_agent.py -v
pytest backend/tests/test_backends.py -v

# Lint & type check
ruff check .
mypy backend/encre

# Desktop type check (main process + renderer)
cd desktop
npm run typecheck

⚡ Quick Start

Basic Agent (Python API)

import asyncio
from encre import EncreAgent

async def main():
    agent = EncreAgent(
        backend="openai",
        model="gpt-4o",
        api_key="...",
    )

    async for event in agent.run("Write a Python script that recursively lists all .py files"):
        if event.type == "text":
            print(event.content, end="")
        elif event.type == "tool_result":
            print(f"\n[Tool: {event.tool_name}] → {event.result[:100]}...")
        elif event.type == "finish":
            print(f"\n\nDone. Reason: {event.reason}")

asyncio.run(main())

With Tool Permission / Safety

from encre import EncreAgent

agent = EncreAgent(
    backend="anthropic",
    model="claude-sonnet-4-20250514",
    api_key="...",
    tool_permission_mode="auto",   # one of: bypass / dont_ask / accept_edits / plan / auto / default
)

Multi-Provider Switch

from encre import EncreAgent

for provider, model, key in [
    ("openai", "gpt-4o", OPENAI_KEY),
    ("anthropic", "claude-sonnet-4-20250514", ANTHROPIC_KEY),
    ("google", "gemini-2.5-pro", GOOGLE_KEY),
]:
    agent = EncreAgent(backend=provider, model=model, api_key=key)
    async for event in agent.run("Explain Rust ownership in one sentence"):
        if event.type == "text":
            print(event.content, end="")
    print("\n" + "=" * 40)

CLI: iClaw Mode

# iClaw is a long-running automation runner (encre/iclaw/__main__.py)
python -m encre.iclaw --help

MCP Servers

from encre.tools.mcp_manager import MCPManager, bootstrap_mcp_servers

# Bootstrap MCP servers from the user's default config path
manager = MCPManager()
await bootstrap_mcp_servers(manager)

🖥️ Desktop Application

Encre Desktop is an Electron + React 19 AI chat application:

Chat: Markdown rendering (markdown-it), syntax highlighting (highlight.js), file attachments
Sessions: Multiple concurrent sessions, branching, fuzzy search (fuse.js)
Settings: Model config, gateway, agent, MCP servers, skills, rules, memory, code index, agents
iClaw Mode: Automation runner with batch operations
Terminal: Embedded terminal (xterm.js + node-pty)
Editor: Monaco Editor with 16+ language workers (TypeScript, JavaScript, Python, Rust, Go, Java, C/C++/C#, PHP, Ruby, Swift, Kotlin, SQL, …)
i18n: English (en.ts) and Chinese (zh.ts) localization, runtime switching
Git integration: status / diff with 5-second cache, in-flight diff tracking
System tray + notifications
Encrypted browser cookie store (AES-256-GCM, key in user data dir)

Launch:

cd desktop
npm start

Package for distribution:

cd desktop
npm run dist
# → Windows: NSIS installer (x64)
# → macOS:   .pkg (x64 + arm64)
# → Linux:   .deb and .rpm (x64)

🔧 Configuration

Configuration Example

# config.yaml
backend: "openai"
model: "gpt-4o"
api_key: "${OPENAI_API_KEY}"

safety:
  tool_permission_mode: "auto"   # bypass / dont_ask / accept_edits / plan / auto / default

memory:
  enabled: true
  max_tokens: 4096

compact:
  strategy: "auto"               # one of the 9 encre.compact strategies
  threshold_tokens: 32000

tools:
  enabled:
    - file_read
    - file_write
    - bash
    - web_fetch
    - web_search
  disabled:
    - browser
    - notebook

Configuration Sources (priority low → high)

Built-in defaults (encre.config.EncreConfig)
Configuration files (YAML, TOML)
Environment variables (prefixed with ENCRE_)
Programmatic configuration passed to EncreAgent(...)

❓ Frequently Asked Questions

Q: How many LLM backends does Encre support? A: 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.

Q: How many built-in tools ship with Encre? A: 36 built-in tools under encre/tools/builtin/, plus a fully pluggable tool registry and an MCP client for external tools.

Q: How do I add a custom tool? A: Subclass EncreTool (defined in encre/tools/base.py), implement execute(**kwargs) -> str and the formatting methods, then register the tool with the ToolRegistry (or use the discovery mechanism in encre/tools/discovery.py).

Q: What are the permission / safety modes? A: 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.

Q: Is this a PyPI library I can pip install? A: 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 ..

Q: How does the memory system work? A: 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.

Q: Does Encre support multi-agent workflows? A: 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).

Q: How does Encre use Rust? A: 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.

Q: How do I build the desktop app for distribution? A: 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/.

Q: Where do the chat-platform adapters live? A: 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.

Q: How do I run Encre as a server? A: 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.

🌏 Community & License

Issues and PRs are welcome!
GitHub: https://github.com/mf2023/Encre
Gitee: https://gitee.com/dunimd/encre
GitCode: https://gitcode.com/dunimd/encre

📄 License & Open Source Agreements

🏛️ Project License

This project uses Apache License 2.0. See LICENSE for the full text.

📋 Dependency Licenses

The 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.

📦 Package	📜 License	📦 Package	📜 License
httpx	BSD-3-Clause	pydantic	MIT
beautifulsoup4	MIT	markdownify	MIT
lxml	BSD-3-Clause	tomli	MIT
tomli-w	MIT	pyyaml	MIT
cryptography	Apache-2.0 / BSD	zero-api-key-web-search	Apache-2.0
pathspec	MPL-2.0	websockets	BSD-3-Clause
Pillow	Historical	playwright	Apache-2.0
tiktoken	MIT	numpy	BSD-3-Clause
loguru	MIT	openai	Apache-2.0
anthropic	MIT	google-generativeai	Apache-2.0
ollama	MIT	groq	MIT
aiohttp	Apache-2.0	discord.py	MIT
slack_bolt	MIT	slack_sdk	MIT
python-telegram-bot	GPL-3.0	dingtalk-stream	MIT
aioimaplib	BSD-3-Clause	aiosmtplib	MIT
torch	BSD-3-Clause	transformers	Apache-2.0
boto3	Apache-2.0	pytest	MIT
pytest-asyncio	Apache-2.0	ruff	MIT
mypy	MIT	pre-commit	MIT
mss	MIT	openpyxl	MIT
pdfplumber	MIT	pyautogui	BSD-3-Clause
pypdf	BSD-3-Clause	PyPDF2	BSD-3-Clause
pytesseract	Apache-2.0	uiautomation	MIT
watchfiles	MIT
serde	MIT/Apache-2.0	serde_json	MIT/Apache-2.0
regex	MIT/Apache-2.0	walkdir	MIT/Apache-2.0
similar	MIT	glob	MIT/Apache-2.0
tempfile	MIT/Apache-2.0	candle-core	Apache-2.0
tokenizers	Apache-2.0	wide	MIT/Apache-2.0
pyo3	MIT/Apache-2.0
electron	MIT	electron-builder	MIT
esbuild	MIT	typescript	Apache-2.0
@xterm/xterm	MIT	@xterm/addon-fit	MIT
@xterm/addon-webgl	MIT	node-pty	MIT
markdown-it	MIT	highlight.js	BSD-3-Clause
fuse.js	Apache-2.0	monaco-editor	MIT
react	MIT	react-dom	MIT
simple-icons	CC0-1.0

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
backend		backend
desktop		desktop
docs		docs
native		native
.gitignore		.gitignore
LICENSE		LICENSE
README.md		README.md
README.zh.md		README.zh.md
build.py		build.py
package-lock.json		package-lock.json
pyproject.toml		pyproject.toml

Folders and files

Latest commit

History

Repository files navigation

Encre

🏗️ Core Architecture

Multi-Language Architecture

Repository Structure

🚀 Key Features

🧠 Multi-Provider LLM Backends (31)

🤖 Built-in Sub-Agents (9)

🛠️ Built-in Tools (36)

🌐 Platform Adapters (18)

🔒 Safety & Permission Engine

💾 Persistent Memory (encre.memdir)

🎯 Skill System (11 bundled)

🤝 Multi-Agent Orchestration

🧱 Native Rust Core (native/crates/encre-core)

🖥️ Encre Desktop (Electron + React 19)

🛠️ Developer Toolchain

🔧 Development Setup

Prerequisites

Clone & Setup

Build Commands

Run Tests & Quality

⚡ Quick Start

Basic Agent (Python API)

With Tool Permission / Safety

Multi-Provider Switch

CLI: iClaw Mode

MCP Servers

🖥️ Desktop Application

🔧 Configuration

Configuration Example

Configuration Sources (priority low → high)

❓ Frequently Asked Questions

🌏 Community & License

📄 License & Open Source Agreements

🏛️ Project License

📋 Dependency Licenses

About

Topics

Resources

License

Code of conduct

Contributing

Security policy

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

💾 Persistent Memory (`encre.memdir`)

🧱 Native Rust Core (`native/crates/encre-core`)

Packages