Skip to content
Back to search

invincat

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.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/dog-qiuqiu--invincat/badge.svg)](/listings/dog-qiuqiu--invincat)

HTML

<a href="/listings/dog-qiuqiu--invincat"><img src="/api/listings/dog-qiuqiu--invincat/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

pip install invincat-cli
cd /path/to/your/project
invincat-cli

On first launch, run `/model` to configure a provider and model.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 262 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Invincat
  2. [![CI](https://github.com/dog-qiuqiu/invincat/actions/workflows/ci.yml/badge.svg)](https://github.com/dog-qiuqiu/invincat/actions/workflows/ci.yml)
  3. [![codecov](https://codecov.io/gh/dog-qiuqiu/invincat/branch/main/graph/badge.svg)](https://codecov.io/gh/dog-qiuqiu/invincat)
  4. [![PyPI](https://img.shields.io/pypi/v/invincat-cli.svg)](https://pypi.org/project/invincat-cli/)
  5. [![Python](https://img.shields.io/pypi/pyversions/invincat-cli.svg)](https://pypi.org/project/invincat-cli/)
  6. [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
  7. ![](https://raw.githubusercontent.com/dog-qiuqiu/invincat/main/data/banner_en.png)
  8. Invincat is a terminal-native AI coding assistant for local repositories. It can inspect and edit files, run shell commands with approval, use web/MCP tools, keep long-term memory, plan before execution, run scheduled tasks, and bridge remote WeCom messages into a project session.
  9. ## Features
  10. - Work directly from your project directory in a terminal UI.
  11. - Read, edit, and create files with approval-gated tool execution.
  12. - Run shell commands under configurable safety controls.
  13. - Use `/plan` to review and approve an execution plan before implementation.
  14. - Keep user and project memory across sessions.
  15. - Create recurring or one-shot scheduled tasks in natural language.
  16. - Extend capabilities through MCP tools, skills, and WeCom bot daemon integration.
  17. ## Quick Start
  18. ```bash
  19. pip install invincat-cli
  20. cd /path/to/your/project
  21. invincat-cli
  22. ```
  23. On first launch, run `/model` to configure a provider and model.
  24. ## Installation
  25. Requires Python 3.11+.
  26. ```bash
  27. pip install invincat-cli
  28. ```
  29. Install from source:
  30. ```bash
  31. git clone https://github.com/dog-qiuqiu/invincat.git
  32. cd invincat
  33. pip install -e .
  34. ```
  35. ## Start
  36. Run Invincat from your project directory:
  37. ```bash
  38. cd /path/to/your/project
  39. invincat-cli
  40. ```
  41. ## Model Configuration
  42. After the first launch, run `/model` to open the model manager.
  43. - Press `Ctrl+N` to register a model.
  44. - Fill in the provider, model name, API key, and optional base URL.
  45. - Select a model and press `Enter` to activate it.
  46. You can also provide credentials through environment variables such as:
  47. ```bash
  48. export OPENAI_API_KEY="..."
  49. export ANTHROPIC_API_KEY="..."
  50. export GOOGLE_API_KEY="..."
  51. export DEEPSEEK_API_KEY="..."
  52. export OPENROUTER_API_KEY="..."
  53. ```
  54. Example for DeepSeek:
  55. ```bash
  56. export DEEPSEEK_API_KEY="sk-..."
  57. ```
  58. Then register a model in `/model` with:
  59. | Field | Value |
  60. | --- | --- |
  61. | Provider | `openai` |
  62. | Model | `deepseek-v4-flash` |
  63. | API Key | `DEEPSEEK_API_KEY` |
  64. | BASE URL | `https://api.deepseek.com` |
  65. Invincat supports a primary model for normal work and an optional memory model for post-turn memory extraction. If no memory model is configured, memory extraction uses the current primary model.
  66. ## Basic Commands
  67. | Command | Description |
  68. | --- | --- |
  69. | `/model` | Configure and switch models. |
  70. | `/plan` | Enter plan-first mode and approve a checklist before execution. |
  71. | `/goal` | Start or inspect a long-running objective. |
  72. | `/memory` | Open the memory manager. |
  73. | `/schedule` | Open the scheduled task manager. |
  74. | `/mcp` | View connected MCP servers and tools. |
  75. | `/threads` | Browse and resume conversation threads. |
  76. | `/help` | Show command help. |
  77. ## Goal Mode
  78. Use `/goal <objective>` when you want Invincat to keep working toward one
  79. long-running objective across multiple turns. Goal mode keeps the active
  80. objective in context, asks before drifting away from it, and only exits when
  81. you complete, cancel, or clear the goal.
  82. Common commands:
  83. | Command | Purpose |
  84. | --- | --- |
  85. | `/goal` | Enter goal mode and use the next message as the objective, or show the active goal. |
  86. | `/goal <objective>` | Create a goal and start the main agent on it. |
  87. | `/goal <objective> --budget 20000` | Create a goal with an optional token budget. |
  88. | `/goal status` | Show the active goal state. |
  89. | `/goal complete [summary]` | Mark the goal complete. |
  90. | `/goal cancel [summary]` or `/exit-goal` | Cancel goal mode. |
  91. | `/goal clear` | Remove the current thread's stored goal state. |
  92. Goal state is scoped to the current thread and stored under
  93. `.invincat/goals/`, so an active goal can be restored when the same thread is
  94. resumed.
  95. ## Memory Management
  96. Invincat keeps durable memory in two scopes:
  97. | Scope | Purpose | Store |
  98. | --- | --- | --- |
  99. | User | Stable personal preferences, recurring instructions, and reusable context for the current agent. | `~/.invincat/<agent>/memory_user.json` |
  100. | Project | Repository-specific decisions, conventions, and facts that should follow the current project. | `.invincat/memory_project.json` |
  101. After completed non-trivial turns, a background memory agent extracts useful
  102. updates and refreshes the memory context for later sessions. Explicit requests
  103. such as "remember this" or "save this" are treated as stronger memory signals.
  104. If no dedicated memory model is configured, extraction uses the current primary
  105. model; for a session-level memory model, use `/model 2 <provider:model>`.
  106. Use `/memory` to inspect and manage memory entries. The viewer supports
  107. switching user/project scope, refreshing, sorting, showing archived items, and
  108. deleting selected entries with confirmation. Prefer this UI over manual JSON
  109. edits because the memory files are managed by the memory subsystem.
  110. ## Plan Mode
  111. Use `/plan` when a task needs review before changes are made. In this mode,
  112. Invincat first produces an execution checklist instead of immediately editing
  113. files or running implementation commands. After you approve the checklist, the
  114. main agent executes the approved steps.
  115. Plan mode is useful for risky, multi-file, ambiguous, or architecture-level
  116. work where you want to inspect the approach first. The planner is limited to
  117. read and planning tools such as file reads, search, web lookup, todos, user
  118. questions, and plan approval; implementation tools are reserved for the
  119. post-approval execution phase.
  120. ## Built-in Subagents
  121. Invincat includes focused subagents that the main agent can call through the
  122. `task` tool for isolated, context-heavy work.
  123. | Subagent | Responsibility |
  124. | --- | --- |
  125. | `explorer` | Codex-style read-only local codebase exploration for locating behavior, tracing call paths, understanding module boundaries, and returning file-backed findings directly to the main agent before implementation. |
  126. | `worker` | Codex-style implementation agent for bounded source-code changes, bug fixes, tests, and local refactors within clearly assigned file or module ownership. It should not commit, push, release, deploy, or expand beyond its assigned scope unless explicitly told. |
  127. | `researcher` | Read-only external/source research, release-note checks, ecosystem comparison, and evidence-backed tradeoff summaries. Local call-path and module tracing should go to `explorer`. |
  128. | `document-worker` | Document-centric parsing, extraction, summarization, conversion, comparison, and quality checks for PDF, DOCX, PPTX, XLSX, Markdown, CSV, and JSON files. It should write only explicit document outputs, not source code, tests, CI, project config, or the primary README. |
  129. These roles are separate so the main agent can keep orchestration and execution
  130. focused while delegated agents handle specialized work in isolated contexts and
  131. return concise findings.
  132. ## Built-in Skills
  133. Skills are lightweight capability packs loaded into the agent when a task
  134. matches their description. They provide focused instructions, workflows, and
  135. supporting scripts without becoming separate agents.
  136. | Skill | Responsibility |
  137. | --- | --- |
  138. | `docx` | Read, create, edit, convert, comment on, and reorganize Microsoft Word `.docx` documents. |
  139. | `pdf` | Read, extract, merge, split, rotate, watermark, create, fill, encrypt, decrypt, OCR, and inspect PDF files. |
  140. | `pptx` | Read, create, edit, combine, split, and analyze PowerPoint decks, slides, templates, notes, and comments. |
  141. | `xlsx` | Read, create, edit, clean, format, chart, validate, and convert spreadsheets such as `.xlsx`, `.xlsm`, `.csv`, and `.tsv`. |
  142. | `skill-creator` | Guide users and agents through creating, updating, validating, and structuring new skills. |
  143. ## Skill Installation and Configuration
  144. Built-in skills are enabled by default. Custom skills can be added at user or
  145. project scope:
  146. | Scope | Directory |
  147. | --- | --- |
  148. | User | `~/.invincat/<agent>/skills/` |
  149. | User shared | `~/.agents/skills/` |
  150. | Project | `.invincat/skills/` |
  151. | Project shared | `.agents/skills/` |
  152. | Built-in | `<package>/built_in_skills/` |
  153. Project skills override user skills with the same name, and custom skills
  154. override built-in skills. Each skill lives in its own directory with a
  155. `SKILL.md` file that defines its `name`, `description`, and instructions.
  156. Some built-in skills rely on document-processing libraries that are not needed
  157. for normal coding sessions. Install the matching extras when you want those
  158. workflows available:
  159. ```bash
  160. pip install "invincat-cli[pdf]"
  161. pip install "invincat-cli[office]"
  162. pip install "invincat-cli[all-skills]"
  163. ```
  164. Office conversion and spreadsheet recalculation workflows may also need system
  165. tools such as LibreOffice, Poppler, Tesseract, or Node.js packages named by the
  166. skill instructions.
  167. For local release checks, install:
  168. ```bash
  169. pip install "invincat-cli[release]"
  170. ```
  171. ## WeCom Bot Daemon
  172. Configure a robot on the enterprise WeChat side to obtain the "Bot ID" and "Secret":
  173. https://developer.work.weixin.qq.com/document/path/101463
  174. Invincat can run a foreground WeCom bot daemon for project-scoped remote turns and scheduled-task delivery.
  175. Configure the bot credentials first:
  176. ```bash
  177. export WECOM_BOT_ID="your_bot_id"
  178. export WECOM_BOT_SECRET="your_bot_secret"
  179. ```
  180. `WECOM_WS_URL` is optional and defaults to `wss://openws.work.weixin.qq.com`.
  181. Set it only when you need to override the WeCom websocket endpoint.
  182. Start the daemon from the project directory:
  183. ```bash
  184. cd /path/to/your/project
  185. invincat-cli wecombot
  186. ```
  187. For a lightweight background process, run it with `nohup`:
  188. ```bash
  189. cd /path/to/your/project
  190. mkdir -p .invincat
  191. nohup invincat-cli wecombot > wecombot.nohup.log 2>&1 &
  192. ```
  193. Stop it by stopping the foreground process or killing the background process.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.