by dog-qiuqiu
A native Python agent CLI built on DeepAgents CLI, featuring an independent memory Agent that captures learnings after each task and delivers efficient AI coding assistance through hierarchical memory management.
# Add to your Claude Code skills
git clone https://github.com/dog-qiuqiu/invincat
A Python-based terminal AI programming assistant — collaborate with AI directly in your project directory: read/write files, execute commands, browse the web, and maintain memory across sessions.

Invincat is designed for real engineering work in local repositories, not demo-only chat.
/plan lets teams review and approve checklists before execution, reducing risky one-shot edits./memory.Invincat uses a multi-agent runtime with clear role boundaries.
User Input enters the session router./plan mode is active, input is routed to the Planner Agent; otherwise to the Main Agent.Main Agent executes tools (file/shell/web/MCP) under approval and middleware guardrails.No comments yet. Be the first to share your thoughts!
Memory AgentMain Agent delegates bounded subtasks to local or async subagents.| Agent | Primary Responsibility | Allowed/Expected Behavior | Hard Boundary |
|------|-------------------------|---------------------------|---------------|
| Main Agent | Execute user tasks end-to-end | Read/write files, run commands, use MCP/tools, coordinate subtasks | Must not directly read/write memory_user.json or memory_project.json |
| Planner Agent (/plan) | Produce and refine executable plans | Read-only context gathering, write_todos, approve_plan, optional clarification via ask_user | No implementation actions (no file edits, no command execution) |
| Memory Agent | Curate durable memory after each completed turn | Score and apply memory ops (create/update/rescore/retier/archive/delete/noop) to user/project stores | Conservative extraction; skips low-confidence or ephemeral facts |
| Local Subagents | Parallelize bounded in-process subtasks | Handle scoped tasks delegated by main agent with explicit instructions | Operate only within delegated scope; main agent remains final integrator |
| Async Subagents | Offload long/remote tasks | Launch/update/cancel remote subagent jobs via async tools | Treated as delegated workers, not primary conversation owner |
aafter_agent) so it does not block user-visible responses.Requirements: Python 3.11+
# Install from PyPI
pip install invincat-cli
Or install from source:
git clone https://github.com/dog-qiuqiu/invincat.git
cd invincat
pip install -e .
# Start in your project directory
cd ~/my-project
invincat-cli
After the first launch, run /model to configure the model and API Key, then you can start the conversation directly.
Run /model command to open the model management interface:

Ctrl+N to register a new modelEnter to activateInvincat uses two model targets:
Primary model: handles normal conversation execution and planner-mode execution handoff.Memory model: used only by the post-turn memory extraction pipeline.| Provider | Example Models |
|----------|----------------|
| anthropic | claude-sonnet-4-6, claude-opus-4-7 |
| openai | gpt-4o, o3 |
| google_genai | gemini-2.0-flash, gemini-2.5-pro |
| openrouter | Supports all models on OpenRouter |
For OpenAI-compatible interfaces (DeepSeek, Zhipu, local Ollama, etc.), simply set the base_url to connect.
| Variable | Description |
|----------|-------------|
| ANTHROPIC_API_KEY | Anthropic API Key |
| OPENAI_API_KEY | OpenAI API Key |
| GOOGLE_API_KEY | Google API Key |
| OPENROUTER_API_KEY | OpenRouter API Key |
| TAVILY_API_KEY | Tavily web search Key (optional) |
Type your question or task directly in the input box and press Enter to send. AI will automatically select the appropriate tools to complete the task:
Search for the latest usage of LangGraph interrupt
/ prefix)/clear
/threads
/model
... ...
Press Tab to autocomplete available commands. See Slash Commands for the complete list.
Use planner mode when you want to discuss and approve a plan before execution:
/plan
Then describe your task in chat. The planner agent will:
write_todos)approve_plan)After approval, planner mode exits and keeps the approved checklist visible. The approved checklist is then handed to the main agent for execution. If you reject the plan, the planner stays in planning mode so you can refine requirements and regenerate the checklist.
Exit planner mode anytime:
/exit-plan
/exit-plan also cancels an in-flight planner turn and drops queued planner handoff actions, so no stale plan execution will continue after exit.
Use @ in your message to reference files, and AI will read and understand their content:
@src/main.py Are there any potential performance issues in this file?
When AI performs operations like file writing, shell commands, or network requests, it will pause by default for confirmation:
Auto-approve Mode: Press Shift+Tab to toggle. When enabled, all tool calls are automatically approved, suitable for trusted task scenarios. The status bar will display an AUTO indicator.
⚠️ It's recommended to enable auto-approve only after you're familiar with the task content.
Press Ctrl+J in the input box to insert a line break, suitable for entering longer code or paragraphs.
A lightweight compression that runs automatically before each model call, no LLM involved, taking <1ms.
How it works: Groups conversation messages by "tool call groups", keeps a dynamic recent window intact, and compresses older large tool outputs in two levels:
cleared-light: richer placeholder near the cutoff (keeps head/tail signals)cleared-heavy: stronger placeholder for older groups (keeps concise summary)Compressible Tool Outputs:
| Tool | Compression Effect |
|------|-------------------|
| read_file | file content → light/heavy placeholder |
| edit_file | diff output → light/heavy placeholder |
| write_file | write result → light/heavy placeholder |
| execute | shell output → light/heavy placeholder |
| grep/glob/ls | search/list output → light/heavy placeholder |
| web_search/fetch_url | web content → light/heavy placeholder |
Not Compressed: agent/subagent results, ask_user responses, MCP tool outputs, compact_conversation results.
Tune micro compression with environment variables:
INVINCAT_MICRO_COMPACT_KEEP_RECENT_GROUPS=3
INVINCAT_MICRO_COMPACT_DYNAMIC_GROUP_FACTOR=12
INVINCAT_MICRO_COMPACT_MAX_KEEP_RECENT_GROUPS=8
INVINCAT_MICRO_COMPACT_LIGHT_NEAR_CUTOFF_GROUPS=2
INVINCAT_MICRO_COMPACT_MIN_COMPRESS_CHARS=240
💡 Micro compression only affects the context sent to the model, does not modify persisted state, and complete history is still saved in checkpoints.
When context window usage exceeds 80%, the system automatically compresses older messages into summaries to free up space, requiring no manual operation. The status bar token count turns orange above 70% and red above 90% as warnings.
/offload
Or equivalently /compact. After execution, it shows how many messages were compressed and how many tokens were freed.
AI can remember your preferences, project conventions, and important information across sessions.
memory_user.json and memory_project.json only, which keeps reads/writes auditable and deterministic.user) from repository conventions (project) to avoid memory pollution.RefreshableMemoryMiddleware is responsible only for loading/rendering/injecting memory.MemoryAgentMiddleware is responsible only for post-turn extraction and structured writes.