CIRI — Contextual Intelligence and Reasoning Interface
Ciri is an open-source, autonomous AI copilot that lives inside your workspace. She is not a coding assistant — she is a general-purpose intelligence that adapts to whatever domain you work in: software engineering, accounting, marketing, branding, sales, legal research, content production, data analysis, or any discipline you train her on.
Ciri builds a deep, persistent understanding of your workspace, connects to your real browser, executes sandboxed scripts, and permanently expands her own capabilities by creating new Skills, Toolkits, and SubAgents — all from a single terminal interface.
Why Ciri?
| Feature | Ciri | Generic AI Chat |
|---|---|---|
| Persistent workspace memory | ✅ Two-level (global + project) | ❌ Stateless |
| Domain-agnostic training | ✅ Any field: dev, finance, marketing… | ❌ General only |
| Self-evolving capabilities | ✅ Builds her own tools | ❌ Fixed toolset |
| Real browser integration (CDP) | ✅ Your sessions & cookies | ❌ Scrapers only |
| Human-in-the-loop approvals | ✅ Per-action, editable | ❌ All-or-nothing |
| MCP Toolkit ecosystem | ✅ Any standard MCP server | ❌ |
| Local-first, private history | ✅ SQLite on-disk | ❌ Cloud |
| Multi-provider LLM | ✅ OpenAI, Anthropic, OpenRouter… | Varies |
What Can Ciri Do?
Ciri's capabilities are defined by the workspace she inhabits and the training she receives via /sync. Examples across domains:
Software Engineering: Read codebases, write and test code, manage git, create PRs, run CI pipelines, refactor, document.
Business Operations: Draft proposals, analyze financials, automate reporting, manage project trackers, generate slide decks.
Marketing & Branding: Research competitors, draft copy, generate visuals, schedule campaigns, analyze engagement data.
Sales & CRM: Qualify leads, draft outreach, summarize call notes, update CRM via MCP toolkits, track pipeline.
Data & Research: Crawl the web for primary sources using your authenticated browser, summarize papers, build data pipelines.
Document Work: Fill PDF forms, process DOCX/PPTX/XLSX files, extract structured data, produce formatted reports.
The key insight: Ciri trains herself to match your domain. Run /sync in a marketing agency workspace and she learns your brand voice, tools, and workflows. Run it in a fintech codebase and she learns your stack, conventions, and release process.
System Architecture
Key Concepts
Skills
Reusable capability packages that give Ciri domain knowledge and executable tools. A skill is a directory containing a SKILL.md (playbook) and a scripts/ folder of Python helpers. Skills live in the core harness (~/.local/share/ciri/skills/) for global availability or your project harness (.ciri/skills/) for workspace-specific ones. Ciri ships with built-in skills for PDF forms, Office documents, web testing, MCP server building, and more.
Toolkits (MCP)
Ciri's ToolkitInjectionMiddleware is an MCP client that connects to any standard Model Context Protocol server. Ask Ciri to "build a toolkit for Slack" or "connect to my PostgreSQL database" and the toolkit_builder subagent generates an MCP server, tests it, and hot-reloads it — no restart required.
SubAgents
Specialized agents with scoped system prompts and tool access. The five built-in subagents (web_researcher, skill_builder, toolkit_builder, subagent_builder, trainer_agent) handle complex delegated tasks. You can define your own in .ciri/subagents/ using YAML configuration.
Core Harness
A two-level filesystem that separates global capabilities (available across all your projects) from project-specific ones. The global harness lives in ~/.local/share/ciri/ (Linux) or equivalent OS data dir, and the project harness in .ciri/ at your workspace root.
Self-Evolution
Run /sync and the Trainer Agent audits your environment, identifies capability gaps, and orchestrates builder subagents to create new Skills, Toolkits, or SubAgents — then hot-reloads them without a restart. The more you use Ciri in a domain, the more specialized she becomes.
Quick Start
# Install
pip install ciri-copilot
# or with uv (recommended)
uv pip install ciri-copilot
# Run
ciri
# On first run, Ciri walks you through model selection.
# Then analyze your workspace:
/sync
Navigation
| Section | What's Inside |
|---|---|
| Getting Started | Installation, first run, model configuration |
| CLI Reference | All /commands, @triggers, keyboard shortcuts |
| Skills Guide | Creating and using domain capability packages |
| Toolkits Guide | MCP server integration |
| SubAgents Guide | Delegation and custom agent roles |
| Architecture | How the graph, middleware, and harness fit together |
| Features | Memory, web research, HITL, autocomplete, script executor |
| Built-in Skills | PDF, Office docs, web testing, and more |
| Internals | Graph execution, middlewares, self-evolution deep dive |
| Use Cases | Real-world walkthroughs across domains |