What Paqad is and what it does

What Paqad is

Paqad is an open-source framework, maintained by Eliyce B.V. and released under the MIT licence, that gives AI coding tools a written description of your project and a set of steps and checks to follow when they change it. You install it as the npm package paqad-ai, which also gives you a command-line tool called paqad-ai.

An AI coding assistant usually opens your repository knowing nothing about it: not your frameworks, not your folder layout, not the rules your team agreed. Paqad writes that knowledge into files inside your project, points each AI tool at those files, and adds checks that run on your own machine.

What Paqad does for your project

• Reads your stack. The paqad-ai onboard command reads files such as package.json, composer.lock or go.mod and works out which frameworks you use. A script does this, not an AI.
• Writes shared instructions. It copies rules for your stack into docs/instructions/rules/ and writes a short entry file for each AI tool you pick, for example CLAUDE.md for Claude Code or AGENTS.md for Codex CLI. Every entry file points at the same material, so all your tools read one source.
• Gives the AI a workflow. Paqad's instructions tell the AI to sort each request into one of a fixed set of workflows (for example feature development, a project question, or a security test) and follow that workflow's steps. For a code change the steps include planning, a specification, development, review and checks.
• Runs checks you can repeat. Commands such as paqad-ai doctor and paqad-ai checks run are scripts. They decide pass or fail from files on disk and the exit codes of your own test and build commands.

Onboarding needs no account and no API key. Optional features, such as a remote search index using OpenAI or Voyage AI, need your own key for that service.

How strict Paqad can be depends on your AI tool

Some AI tools let outside programs run at fixed moments, for example just before the AI edits a file or when it finishes its turn. These small programs are called hooks. Paqad can only stop or record work at the moments a tool offers.

• Claude Code and Codex CLI: Paqad installs hooks that can block an edit until the framework is loaded and that check the work at the end of a turn. Codex CLI runs project hooks only after you approve them once inside Codex with /hooks.
• Gemini CLI: one hook runs when the AI finishes a turn. It records evidence and runs the end-of-turn check, but it does not block anything.
• Cursor, GitHub Copilot, Windsurf, Continue, Junie, Antigravity, Aider and JetBrains AI Assistant: no Paqad hooks run. The AI is told to follow the workflow and run Paqad's commands itself, and nothing forces it to.

Your own tool settings matter too. If hooks are switched off or not trusted in your tool, they do not run. The adapters overview covers each tool.

Who decides what: a script, the AI, or you

Decided by	Examples
A script (the same input always gives the same result)	Stack detection, the files written at onboarding, every doctor check, reading test results, the pass or fail of checks run
The AI (model judgement)	Choosing the workflow for a message, writing a plan or specification, writing documentation in the create documentation workflow, judging whether a review finding matters
You	Which AI tools to set up, which optional features to switch on, approving hooks in Codex, answering when a workflow stops to ask you (a decision pause), what you commit

Key terms used across these docs

• Pack: a folder shipped with Paqad that describes one framework or project type, such as Laravel, React or a Node command-line tool. It says how to recognise the framework, which rules and tool guides to copy, which MCP servers to suggest, and how to read its test results. Its description file is pack.yaml.
• Adapter: the part of Paqad that knows one AI tool's file formats. It writes that tool's entry file, its MCP settings and, where the tool supports them, its hooks.
• Entry file: the file an AI tool reads first, such as CLAUDE.md. Paqad's version is a few lines long and points to .paqad/framework-path.txt, which leads to the installed framework.
• Capabilities: the three rule sets content, coding and security. content is always on. coding and security are switched on together for code projects.
• MCP (Model Context Protocol): a standard way for an AI tool to use extra tools and data sources, called MCP servers.
• RAG (retrieval-augmented generation): an optional search index over your code and documents that hands the AI a few relevant snippets. It is off until you switch it on.

Where Paqad keeps its files

Location	What is there
.paqad/	The project profile, team settings, detection results, decision records and other framework data. Paqad writes its own .paqad/.gitignore so per-machine files stay out of git.
docs/instructions/	Rules, stack tool guides and workflow files the AI reads. The create documentation workflow adds stack, architecture and design-system documents here later.
Entry files	CLAUDE.md, AGENTS.md, GEMINI.md and others, one for each tool you chose.
~/.paqad-ai/current	A link in your home folder to the installed framework, created when you first onboard a project.

Where to go next

Check you have Node.js 22 or later, then follow Installation and the Quick start. For the full picture of what happens during onboarding and during an AI session, read How Paqad works. The source code is on GitHub.