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.
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.
Why Invincat
Invincat is designed for real engineering work in local repositories, not demo-only chat.
Terminal-native workflow: stay in your project directory and use AI without switching IDEs or browser tabs.
Execution with guardrails: shell/file/network actions are approval-gated by default, with optional auto-approve for trusted flows.
Plan-first delivery mode: /plan lets teams review and approve checklists before execution, reducing risky one-shot edits.
Long-context durability: micro compression + offload keep long sessions usable without losing operational history.
Practical memory model: user/project memory stores persist conventions across sessions and are inspectable via /memory.
Extensible architecture: MCP tools, skills, and subagents allow adapting the assistant to team-specific workflows.
Agent Architecture
Invincat uses a multi-agent runtime with clear role boundaries.
Execution Flow
User Input enters the session router.
If /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.
After a non-trivial turn completes, runs asynchronously to extract durable user/project memory updates.
For OpenAI-compatible interfaces (DeepSeek, Zhipu, local Ollama, etc.), simply set the base_url to connect.
Environment Variables
| 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) |
Basic Usage
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
Command Mode (/ prefix)
/clear
/threads
/model
... ...
Press Tab to autocomplete available commands. See Slash Commands for the complete list.
Plan Mode
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:
analyze requirements with read-only tools
write a todo list (write_todos)
ask for explicit approval (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.
File References
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?
Tool Approval
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.
Input Line Breaks
Press Ctrl+J in the input box to insert a line break, suitable for entering longer code or paragraphs.
Context Management
Micro Compression
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)
💡 Micro compression only affects the context sent to the model, does not modify persisted state, and complete history is still saved in checkpoints.
Auto Compression
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.
Manual Compression
/offload
Or equivalently /compact. After execution, it shows how many messages were compressed and how many tokens were freed.
Memory System
AI can remember your preferences, project conventions, and important information across sessions.
Memory Architecture Highlights
JSON single source of truth: runtime memory uses memory_user.json and memory_project.json only, which keeps reads/writes auditable and deterministic.
Dual-scope isolation: separates cross-project personal preferences (user) from repository conventions (project) to avoid memory pollution.
Read/write pipeline decoupling:
RefreshableMemoryMiddleware is responsible only for loading/rendering/injecting memory.
MemoryAgentMiddleware is responsible only for post-turn extraction and structured writes.
The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
