Skip to content

The Dosi plugin

The plugin is the quickest way to use Dosi from a coding agent. One install gives the agent dosi itself, a set of skills that know how to connect to a warehouse, build a semantic model and answer through it, and hooks that keep your passwords out of the conversation. In Claude Code and Codex it also starts dosi's MCP server for the session. There is nothing else to start and no config to write: install it, open your project, and ask a data question.

The source is Datus-ai/dosi-plugins.

Pick your agent

  • Claude Code

    The full plugin: MCP tools, skills, hooks, and a status line, /dosi and a lineage pane.

  • Codex

    MCP tools, skills and hooks.

  • DeepSeek Harness

    Skills and hooks; dosi runs through its CLI.

  • Other agents

    Gemini CLI, Cursor, OpenCode and the rest: the skills and dosi, in one sentence to the agent.

What happens on first use

On its first session the plugin downloads the newest dosi release into its own data folder, in the background (about ten seconds). It never touches a dosi you installed yourself, and it never runs a release older than the one it needs. In mainland China, set DOSI_SOURCE=oss to download from the mirror.

It stays on that release until you ask. Say "upgrade dosi" (or ask which version runs) and the agent checks for a newer release and installs it. The plugin also checks once a day and mentions a new release once, at the end of an answer.

What the agent can do

Skill When it is used
dosi-connect You ask to connect, or ask a data question with no connection yet. It reads your dbt profiles or Cube .env through dosi migrate conf, connects local files directly, or writes a warehouse entry from a template
dosi-model You ask for a semantic model, a new metric, or a change to one. It reads the schema with your own database client, writes dosi/model.yaml, and validates it
dosi-query Any data question: numbers, trends, breakdowns, rankings, lists of records, why a metric changed
dosi-view "How is this computed?", "where does this number come from?", lineage graphs
dosi-ontology You ask about business concepts, or accept the plugin's offer to build an ontology
dosi-upgrade "Which dosi version is this?", "upgrade dosi"

Answers come from the model's metrics, computed by dosi: the agent does not write SQL against tables the model covers. It gives the generated SQL when you ask for it. Where the agent has dosi's MCP tools it calls them; elsewhere it runs the same commands through the dosi CLI.

Two helper commands come with the modeling skill. dosi-reconcile checks metrics against reference numbers cell by cell (a report table you already trust, read with your own client). dosi-fill-derived writes each derived metric's expanded expression from dosi's own computation, so it is never typed by hand.

Your passwords stay out of the conversation

The plugin is built so that a password never passes through the model:

  • The agent never opens dosi-connections.yaml, dbt profiles.yml, .env files, secrets.env or database client settings. It only checks that they exist; dosi reads them. In Claude Code, Codex and DeepSeek Harness a hook blocks such reads.
  • For a warehouse password, the agent writes a ${NAME} placeholder and asks you to fill it in yourself: replace it in dosi-connections.yaml (git-ignored), or put NAME=... in ~/.config/dosi/secrets.env. The next call picks it up, with no restart.
  • To look at tables and columns while modeling, the agent uses the database client you already have, set up to log in by itself (a MySQL login path, a Postgres service, a SnowSQL connection). It never puts a password on the command line and never installs a client.

Differences between agents

Claude Code Codex DeepSeek Harness
dosi's MCP tools yes yes no; the skills use the CLI
Config-read guard yes yes yes
Validation after each model edit yes yes yes
No permission prompts for dosi's own calls yes (Codex's own rules) (DeepSeek Harness's own rules)
Status line, /dosi and the lineage pane yes no no
Feature suggestions (lineage, ontology) yes no no

Files in your project

dosi/model.yaml          # the semantic model: commit it
dosi/ontology.yaml       # only once you build an ontology: commit it
dosi/mapping.yaml        # the ontology's mapping onto the model: commit it
dosi-connections.yaml    # connections; may hold passwords, so it is git-ignored

Scratch files (reference rows, trial models) go under dosi/build/.

Troubleshooting

Symptom Fix
dosi_installing The first download is still running. Wait a few seconds; the agent retries on its own
install_failed behind a restricted network Set DOSI_SOURCE=oss (mirror in mainland China), then start a new session
The agent runs dosi in the shell instead of the MCP tools The MCP server did not start, or the agent has none (DeepSeek Harness). See your agent's page
The query tools still run the old dosi after an upgrade Start a new session, so the MCP server restarts on the new release

Where to next