Start using vaultspecLink to Start using vaultspec
vaultspec keeps research, decisions, and plans with your project instead of losing them in agent conversations. How vaultspec works explains the records.
This page takes about five minutes to read. You’ll download Core, install it in a project, create a record, and check it with your coding agent. Downloads may take longer.
Before you startLink to Before you start
Install uv, then open a
terminal in your project’s root folder. Run the commands here from that folder.
Core works without vaultspec-rag, a graphics processor (GPU), or a TypeSafe API
key. vaultspec-rag is optional, but the workflow is designed around it: agents look
for evidence by meaning first, and fall back to listing and grep when it isn’t there.
Download and installLink to Download and install
Command
uvx vaultspec-core --version
uvx vaultspec-core install
uvx vaultspec-core doctor
The first command downloads Core if needed and prints its version. Installation
creates .vault/ for records, .vaultspec/ for workflow instructions, and your
coding agents’ configuration.
Look for framework ok and clean vault checks in the doctor’s output.
Already installed? Follow the update instructions.
For other options, see installation details.
Create your first recordLink to Create your first record
Command
uvx vaultspec-core vault add research --feature notes-search --title "Search project notes"
uvx vaultspec-core vault list --feature notes-search
uvx vaultspec-core status
The first command prints Created: followed by a dated Markdown path. Open that
file in your editor: it’s a research template, ready for findings. Creating a
template does not perform research or start a plan.
The list shows the record. Status shows notes-search with one document and, in
a fresh project, no plans in flight. Existing project work also appears.
Check it with your agentLink to Check it with your agent
For the agent step, open the project in an agent with the Core Model Context Protocol (MCP) server enabled. Send this prompt:
Prompt for your agent
Use the vaultspec-core MCP status tool to show the status of this project. Tell me which features exist and whether any plan is in flight. Do not change any files.
The agent should report the same feature and plan state as the terminal. This prompt was tested with Codex. If the tool isn’t available, follow the connection checks.
Continue when you need moreLink to Continue when you need more
Run a feature: evidence, decisions, implementation, and review.
Use the command line: create records, find work, and check it.
Add project search: set up vaultspec-rag, the semantic search the workflow leads with.
TypeSafe API integration and environment loading: separate keys, one settings order, and where
.envis read.Core CLI and vaultspec-rag CLI references: all commands and options.
If a check fails, use workspace verification; if search results look wrong, see search troubleshooting. For help, report the command, version, and error in the Core issue tracker.