Yim

English | 简体中文

Documentation | Changelog | Security | Contributing | Code of Conduct

Yim — A complete AI Agent project. This is a monolithic project containing Python agent framework, Rust native core, and Yim Desktop — not individual packages for separate installation. Backend-agnostic, multi-provider, with streaming tool calls, safety engine, persistent memory, multi-agent orchestration, and a rich desktop UI.

🏗️ Core Architecture

Multi-Language Architecture

Yim adopts a multi-language architecture with three major components, enabling each layer to use the most appropriate language for its domain:

Language	Component	Purpose
Python	yim/ + root modules	AI Agent framework core — agent loop, 31 backends, 35 built-in tools, safety, memory, skills, swarm, hooks, LSP
Rust	crates/yim-core	Native high-performance library — file I/O, regex search, glob, diff, sandbox, tokenizer
Rust	crates/yim-py	PyO3 bindings exposing Rust to Python as yim._native
TypeScript	desktop/	Yim Desktop — Electron-based desktop application with rich AIChat UI (iClaw mode, settings, sessions, search)

This is a complete project — not a standalone library or individual packages for separate installation. All components (Python framework, Rust native core, Yim Desktop) are developed and versioned together as one monolith. Clone the entire repository to use all components.

Repository Structure

d:\yim/
├── agent.py                  # Agent entry point
├── config.py                 # Global configuration
├── pyproject.toml             # Python build & dependencies
├── Cargo.toml                 # Rust workspace root
├── __init__.py                # Public API surface
├── native.py                  # Rust native bridge
│
├── yim/                      # Python agent framework
│   ├── agent.py              # YmiAgent — public API
│   ├── loop.py               # YmiLoop — execution loop
│   ├── session.py            # YmiSession — conversation state
│   ├── safety.py             # YmiSafetyEngine — 6 permission modes
│   ├── config.py             # Configuration management
│   ├── crypto.py             # AES-GCM encryption
│   ├── backends/             # 31 LLM providers
│   ├── tools/builtin/        # 35 built-in tools
│   ├── tools/mcp.py          # MCP client
│   ├── hooks/                # YmiHookSystem
│   ├── memdir/               # Persistent memory system
│   ├── skills/               # Skill registry + 11 bundled skills
│   ├── swarm/                # Multi-agent system
│   ├── task/                 # Task manager & executor
│   ├── server/               # WebSocket server + admin API
│   ├── channels/             # Transport: websocket, terminal, HTTP API
│   ├── adapters/             # External platform adapters
│   ├── gateway/              # Gateway client/server
│   ├── compact/              # Context compaction (3 strategies)
│   ├── lsp/                  # LSP client
│   ├── codebase/             # Code indexer (BM25 + dependency graph)
│   ├── computer/             # Desktop & browser automation
│   ├── evolution/            # Meta-cognition, reflex loop
│   ├── feedback/             # Error correction learner
│   ├── notebook/             # Interactive Python kernel
│   ├── plugins/              # Plugin registry
│   ├── profile/              # User profile inference
│   ├── soul/                 # Soul system files
│   ├── spec/                 # Spec document engine
│   ├── prompts/              # Prompt blocks, skills, safety, goals
│   ├── sandbox/              # Docker container sandbox
│   ├── search/               # Web search (DuckDuckGo)
│   ├── learning/             # Skill generation + consolidation
│   ├── rules/                # Rules loader
│   ├── thinking/             # Thinking config resolution
│   ├── utils/                # ID generation, token counting, types
│   ├── iclaw/                # iClaw mode (automation runner)
│   └── rollback.py           # Git-based rollback
│
├── crates/                   # Rust workspace
│   ├── yim-core/             # Native core
│   │   ├── src/fs.rs
│   │   ├── src/search.rs
│   │   ├── src/diff.rs
│   │   ├── src/shell.rs
│   │   ├── src/sandbox.rs
│   │   ├── src/tokenizer.rs
│   │   └── src/embedding.rs
│   ├── yim-py/               # PyO3 bindings → yim._native
│   │   └── src/lib.rs
│   ├── yim-core/Cargo.toml
│   └── yim-py/Cargo.toml
│
├── desktop/                  # Electron desktop application
│   ├── main.ts               # Electron main process
│   ├── preload.ts            # Context bridge
│   ├── build.js              # esbuild configuration
│   ├── package.json          # Node.js dependencies
│   ├── electron-builder.yml  # Build config
│   ├── renderer/             # Frontend
│   │   ├── index.html
│   │   ├── styles.css
│   │   ├── bundle.js
│   │   ├── src/              # TypeScript sources
│   │   │   ├── app.ts
│   │   │   ├── chat.ts
│   │   │   ├── session.ts
│   │   │   ├── settings.ts
│   │   │   ├── state.ts
│   │   │   ├── stream.ts
│   │   │   ├── ws.ts
│   │   │   ├── search.ts
│   │   │   ├── i18n.ts
│   │   │   ├── locales/
│   │   │   └── icons.ts
│   │   └── vs/               # Monaco Editor
│   └── renderer/vs/          # Monaco Editor (bundled)
│
└── tests/                    # Python test suite

🚀 Key Features

🧠 Multi-Provider Backend (31)

• OpenAI, Anthropic Claude, DeepSeek, Google Gemini, Groq, Ollama, Local (HuggingFace)
• Alibaba (Qwen), Tencent, Xiaomi, Kimi, GLM, Minimax, Arcee, Novita, OpenRouter
• AWS Bedrock, GitHub Copilot, LM Studio, OpenAI Compatible, OpenAI SSE
• AI Gateway, Kilocode, OpenCode, Failover, Router, Retry, MCP Catalog
• Unified streaming interface, automatic thinking resolution

🛠️ Rich Tool System (35)

• File: read, write, edit, apply patch, find, grep, glob, pdf, spreadsheet
• Execution: bash, bash_io, docker, deploy, agent spawning
• Web: fetch, search, browser automation (Playwright)
• Development: LSP client, notebook (IPython kernel), database
• Multi-agent: task_create, task_get, task_list, task_output, task_stop, task_update
• Other: todo, memory, image, cron (create/delete/list), desktop, git, rest_client
• MCP client (Model Context Protocol)

🔒 Safety Engine

• 6 permission modes: bypass / dont_ask / accept_edits / plan / auto / default
• Dangerous command pattern detection
• SSRF validation via DNS resolution + CIDR blocklists
• Docker container sandbox with seccomp profiles
• Auto safety classifier (AI-based permission decisions)

💾 Persistent Memory

• Frontmatter-parsed .md file storage in memdir
• MEMORY.md entrypoint index with aging/freshness tracking
• Semantic memory search (NumPy-based similarity)

🎯 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

🤝 Multi-Agent Orchestration

• Swarm: teammate wrapper, swarm manager (concurrency-limited), async mailbox
• Orchestrator: blackboard, consensus, roles, planner
• Task: typed CRUD with bash/agent/workflow executors

⚡ Rust Native Performance

• Fast file I/O (native read/write), regex search, glob, unified diff
• Sandboxed shell execution with seccomp
• BPE tokenizer for efficient context window management
• SIMD-accelerated pattern matching (optional)
• Semantic embeddings via Candle (optional)

🖥️ Yim Desktop (Electron-based)

• Full-featured AI Chat UI with session management
• iClaw mode (automation runner)
• Settings panels: models, gateway, agent, MCP, skills, rules, memory, index
• Search (fuzzy via Fuse.js), file browser, workspace
• Terminal emulator (xterm.js + node-pty), Monaco Editor
• Multi-language support (en/zh), notifications, voice input
• Encrypted browser cookie store (AES-256-GCM)

🔧 Developer Extras

• Context compaction: compact, summarize, drop strategies
• LSP client: Python, TypeScript, JavaScript, Rust, Go
• Codebase indexer: BM25 search + dependency graphs
• Evolution: meta-cognition, reflex loop, strategy optimization
• Feedback learner: Jaccard similarity-based error correction
• Interactive notebook (IPython kernel)
• Plugin system, profile inference, soul system
• WebSocket server with admin API, session manager
• Spec document engine, goal system, scheduler

🔧 Development Setup

Prerequisites

• Python: 3.11+
• Node.js: 18+ (for desktop app)
• Rust: 1.65+ (optional, for native extension build)
• Platforms: Linux (x64, arm64), macOS (x64, arm64), Windows (x64)

Clone & Setup

# Clone the repository
git clone https://github.com/mf2023/Yim.git
cd yim

# --- Python Agent Framework ---

# Install core dependencies (editable)
pip install -e .

# Install with development dependencies
pip install -e ".[dev]"

# Install optional backends 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 ".[telegram]"        # Telegram adapter
pip install -e ".[local]"           # Local model backend (PyTorch)

# Install Rust native extension (requires Rust toolchain)
pip install -e ".[native]"

# Install all extras (except native — needs local Rust build)
pip install -e ".[anthropic,ollama,aiohttp,discord,slack,telegram,dingtalk,email,local,aws]"

# --- Desktop Application ---

cd desktop
npm install

# Playwright browsers (for browser automation tool)
playwright install

Build Commands

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

# Rust: build native extension
cd crates
cargo build --release

# Desktop: build & run
cd desktop
npm run build        # Bundle TypeScript with esbuild
npm start            # Build + launch Electron

# Desktop: package for distribution
npm run dist         # Build + electron-builder (NSIS/DMG/AppImage)

Run Tests & Quality

# Python tests
pytest -v
pytest tests/test_agent.py -v

# Lint & type check
ruff check .
mypy yim

# Desktop type check
cd desktop
npm run typecheck

⚡ Quick Start

Basic Agent (Python API)

import asyncio
from yim import YmiAgent

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

    async for event in agent.run("Write a Python script to list all .py files recursively"):
        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 yim import YmiAgent

agent = YmiAgent(
    backend="anthropic",
    model="claude-sonnet-4-20250514",
    api_key="...",
    tool_permission_mode="auto",
)

Multi-Provider Switch

from yim import YmiAgent

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 = YmiAgent(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)

🖥️ Desktop Application

Yim Desktop provides a full-featured AI chat interface:

• Chat: Markdown rendering (highlight.js), code blocks, file attachments
• Sessions: Multiple concurrent sessions, branching, search
• Settings: Model config, gateway, agent, MCP servers, skills, rules, memory, index
• iClaw Mode: Automation runner with batch operations
• Terminal: Embedded terminal (xterm.js + node-pty)
• Editor: Monaco Editor for code editing
• i18n: English and Chinese localization

Launch:

cd desktop
npm start

🔧 Configuration

Configuration Example

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

safety:
  tool_permission_mode: "auto"

memory:
  enabled: true
  max_tokens: 4096

compact:
  strategy: "auto"
  threshold_tokens: 32000

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

Configuration Sources (priority low → high)

1. Default configuration
2. Configuration files (YAML, TOML)
3. Environment variables (prefixed with YIM_)
4. Programmatic configuration at agent creation

❓ Frequently Asked Questions

Q: How many LLM backends does Yim support? A: 31 backends including OpenAI, Anthropic, DeepSeek, Google Gemini, Groq, Ollama, Local (HuggingFace), Alibaba, Tencent, Xiaomi, Kimi, GLM, Minimax, Arcee, Novita, OpenRouter, AWS Bedrock, GitHub Copilot, and more.

Q: How do I add a custom tool? A: Extend YmiTool (ABC) in yim/tools/base.py, implement execute(**kwargs) -> str and format methods, then register with the tool registry.

Q: What are the 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).

Q: Is this a PyPI library I can pip install? A: No. This is a complete project containing Python, Rust, and Electron/TypeScript code. All components are developed and versioned together as one monolith. To use Yim, clone the repository and follow the Development Setup guide.

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. The system tracks freshness and automatically prunes aged entries. Semantic search uses NumPy-based similarity matching.

Q: Does Yim support multi-agent workflows? A: Yes. The Swarm system provides teammates, concurrency-limited swarm managers, async mailboxes, and an orchestrator. The Task system provides typed task CRUD and bash/agent/workflow executors.

Q: How do I build the desktop app for distribution? A: Run npm run dist in the desktop/ directory. Uses electron-builder to produce NSIS (Windows), DMG (macOS), or AppImage (Linux) packages.

🌏 Community & License

• Welcome to submit Issues and PRs!
• GitHub: https://github.com/mf2023/Yim
• Gitee: https://gitee.com/dunimd/yim
• GitCode: https://gitcode.com/dunimd/yim

📄 License & Open Source Agreements

🏛️ Project License

This project uses Apache License 2.0. See LICENSE file.

📋 Dependency Licenses

📦 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
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
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