Knowns CLI
Tasks, docs, specs and decisions live as markdown files in your repository, and the agent reads them through the CLI and MCP
- 251 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- The setup commands write MCP configuration, skills and hooks into the agent's directories
- The npm installer retrieves an executable binary from an external source
- Through MCP the agent can read and write the project's tasks, docs and memory
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add cli/knownsDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- The setup commands write MCP configuration, skills and hooks into the agent's directories
- The npm installer retrieves an executable binary from an external source
- Through MCP the agent can read and write the project's tasks, docs and memory
This is third-party code. Review the repository files before installing.
What it does
Knowns is a command-line program that keeps a project's context for an AI agent in a .knowns/ directory inside the repository. It holds tasks with acceptance criteria and an implementation plan, nested markdown documents that link to each other, specs, templates for code generation and three levels of memory: project, session and global. The agent can resolve references like @doc/patterns/auth and @task-KN-4F7Q2M itself. The files are plain and can be committed to Git, with no cloud needed. The agent gets this context through an MCP server and through CLI commands. Semantic search by meaning uses local ONNX models. The knowns doctor command checks project setup, search, language servers and agent connections before you start. For code there are LSP tools: symbols, definitions, references and symbol-based edits. For Claude Code and Codex the program syncs a set of /kn-* and $kn-* skills: kn-init reads the docs and loads memory, kn-plan builds a plan for a task, kn-implement carries it out and ticks off the criteria, kn-review reviews code with P1–P3 priorities and kn-commit prepares a commit. System decisions are stored as separate records: a new decision starts as a draft and becomes current once its linked evidence is verified.
Who it is for. For developers and teams who work daily with Claude Code, Codex, Cursor or OpenCode and are tired of explaining the architecture to the agent at the start of every session.
Good fit when
- The agent forgets decisions between sessions and you want to keep them in the repository as records with a lifecycle
- You want to track tasks with acceptance criteria that the agent checks off itself
- The project has a lot of documentation and you need offline search by meaning
- A team onboards new members or agents and wants to give them one shared context in the .knowns/ directory
- You need Handlebars templates for generating repetitive code with knowns template run
Not a fit when
- The project is tiny and a single CLAUDE.md or AGENTS.md is enough
- You need a cloud task tracker with shared access: Knowns stores data locally in files
- You only want memory for assistant conversations with no tie to a repository
Example request
Run /kn-plan 42: take the task, read the linked docs and write a plan, then wait for my approvalLimitations
Prebuilt binaries support Windows, macOS and Linux. The npm wrapper obtains a platform package or downloads an archive from GitHub Releases; Go is needed only for source builds. The first semantic search may need a model download, after which indexing runs locally.
Setup writes configurations, skills and hooks for some clients. Global setup can run separately; project setup requires .knowns. MCP exposes documents and code to your agent, so privacy depends on its model and the Git server receiving the repository. Team synchronization is still planned.
How to disable. Remove the MCP configuration and the skills that knowns setup added, then delete the .knowns/ directory and the pointer files from the project. Uninstall the program itself with npm uninstall -g knowns or brew uninstall knowns.
FAQ
How do I connect Knowns to Claude Code?
Install the program, run knowns init in the project, then knowns setup claude --global. The agent gets MCP, the /kn-* skills and runtime memory hooks. For Codex use knowns setup codex --global, for OpenCode knowns setup opencode --global.
Where does Knowns keep its data, and can I share it through Git?
The data sits in the .knowns/ directory of the repository as plain files. You can commit them, and teammates get the same tasks, docs and memory after cloning. Run knowns doctor to check the project after a clone.
How do system decisions differ from decisions in a spec?
Spec decisions are locked rules D1, D2 and so on inside an approved spec that implementers must follow. System decisions are separate records of durable project changes: they start as drafts and become current once linked evidence is verified.
Does semantic search need a key?
The local model needs no API key. Prepare it with `knowns search --setup` and rebuild the index. Search then needs no external API, but the initial model download may require a network connection.
How do I open the Knowns web UI?
With knowns browser --open. A local page opens with a task kanban board, a document browser, a knowledge graph and mermaid diagrams.
Discussion
No questions or reviews yet.
Related
CLI toolsOver twenty skills for coding agents: MCP and hooks, plan mode, a bug-fix protocol, prompting and a bash safety hook
Work modes for AI coding agents: a light solo mode for daily tasks and /man with a plan, checks and review for big changes
A CLI that generates and maintains AI context files, CLAUDE.md, Cursor rules, AGENTS.md and Copilot instructions, keeping them accurate as code changes
A Python terminal coding agent in the manner of Claude Code: reads the repository, edits files, runs commands, with memory, sub-agents and MCP
A Rust coding agent with a native GUI, a terminal mode, an ACP mode for Zed and an MCP server
A Claude Code working configuration: a planner with per-milestone review, sub-agents and skills for analysis, refactoring and docs sync
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| Knowns (this card) | no | 251 | ||
| Spec Kit | no | 147,764 | the specify CLI installs spec-driven development commands into a project; Knowns stores tasks, docs and memory | |
| Trellis | no | 15,100 | a workflow scaffold: specs, tasks and session logs also live in the repository | |
| Basic Memory | no | not required | 4,495 | long-term agent memory in Markdown files; Knowns adds tasks with acceptance criteria |
README in short
A local web interface shows a kanban task board, documents and their links. The program uses MIT, and project data can be read and edited as ordinary files.