DevHub tools for AI agents

Configure an agent from a persona. Call agent_list first for the visible personas, clients, repositories and brains. Created switched off until the owner turns it on.

The agents configured for this repository (what each does, which client runs it, whether it can run at all), then what agent_create can be given: clients with their models and reasoning levels, personas, repositories. Call before doing work another agent is set up for, and before creating one.

Use for tasks assigned to an agent from agent_list. Returns an answer or RUNNING <runId> after 45 seconds. RUNNING is not failure: call agent_run_status with wait; do not retry.

Use after RUNNING; wait here, not by rerunning. RUNNING is not failure; answers last an hour.

Use to change an agent's configuration or personal name. Names and labels are cosmetic; widening capabilities switches it off for owner review. Cannot switch it on.

Read a binary file as Base64; images come back as viewable content. Use file_read for text.

Write a binary file from Base64 — images, audio, PDFs, archives, up to 20 MB. Use file_write for text.

Repeated errors and slow tools with recommendations. Use when something fails intermittently and you need the pattern rather than one event.

Inspect individual MCP calls. Use when a specific tool call failed and you need its arguments, error and timing.

Success rate and duration totals over a window. Use to answer "is anything broken right now" before digging into individual events.

The same read as context_pull, without emptying the queue: the queued vault notes, code symbols and overviews merged into one payload with its manifest. Use it when the queue is shared and whoever queued it still needs it there; use context_pull when you are the one consuming it.

Take the context the user queued for you in Context AI: vault notes, code symbols and repository overviews, merged into one payload with a manifest saying where every part came from. Reading it empties the queue. Call it at the start of a task, before searching on your own.

Create a repository directory. Rarely needed on its own — file_create makes missing parents.

List monitors with their IDs. Call before display_screenshot to pick one.

Capture a monitor as PNG. Use when you need to see what the user sees — a running app, a rendered view, a visual bug.

Create a new repository file and any missing parents, failing if it already exists. Use file_write instead when replacing an existing file is intended.

Delete a repository file or directory. Irreversible; confirm with the user first unless they asked for it.

Apply several line-range edits to one repository file in one call, all or none. Take the line numbers and expectedHash from file_read; ranges refer to the file as you read it. Prefer this over file_replace when you know where the change goes.

Read one repository file, whole or a line range. Pass offset and limit when a repo_* result already told you which lines to look at.

Change known exact text in a repository file, one pair or several in one call. Use when you know the text but not the line, e.g. after files_search; for changes at known lines use file_edit.

Create or fully overwrite a repository file. Prefer file_replace for edits — overwriting discards anything you did not include.

Browse a repository directory. Use to discover paths; use repo_symbol_search when you are looking for a definition.

Grep a repository for arbitrary text. Use for strings, config values and comments; use repo_symbol_search for definitions, which is far cheaper.

Write a document into an investigation: what is there (analysis), a way in (variant), what to do (plan), or what was settled (finding). Call when you have finished a piece of the looking, before moving to the next — two ways of doing the same thing are two documents, not one rewritten.

Mark an investigation finished. Call it when a plan came out of the spike and that plan has landed: it leaves investigation_list and stays readable by id. Removal is a different decision, made later.

Open a container for a spike: what is being looked into, and the ticket it is being done for when there is one. Documents go in it with investigation_add.

Spike analyses this DevHub holds: what was looked into, and what came out of it. Call before starting an investigation — the ground may already have been covered, and a variant somebody rejected is worth knowing about. Closed ones are left out: they are finished work, still readable by id.

One investigation in full, or one document in it. Use after investigation_list shows one that covers what you are about to look into.

Fetch one Business Context chunk in full, including the fields knowledge_search omits. Use after a search when you need the complete source; pass the same workspaceId or vaultId you searched with, or neither if the search named neither.

Rebuild the Business Context index. Use after editing vault notes when knowledge_search is not returning them yet.

Check whether Business Context is indexed and current before trusting a knowledge_search result.

Ask the vaults a question: decisions, canon, guidelines — "why" and "what is the rule". Built from the knowledge folders only, so a miss is not absence: `vault_overview` says which folders, `vault_files_search` reads all of them. For code use repo_symbol_search. Omit both ids to search this endpoint's scope.

Call when something went wrong and the reason it went wrong is worth stating for the next session. One note per lesson, not a summary of the session. Not for how the work is done here: that is memory_note.

Writes into the user's own collection. Call library_list first. Needs id, title, groups. Skill: when + router (+reference). Rule: rule (+paths). Command: when + command. Persona: when + agent (+skills, rules, commands). Profile: when + skills/rules/commands (+profile). Instruction: when + instruction.

Change one the user owns, fields as library_create. Use that one for a new one; what ships with DevHub or comes from a repository is edited where it lives.

One of them in full, read into this session only — nothing is installed and nothing is written. Use when library_list shows one that covers what you are doing, or to find out what a rule you are working under actually says.

What Vartari DevHub holds of one kind that this folder does not carry: skills, rules, commands, personas, profiles or instructions, one line each with the field you decide on. Call before writing one — most of what you would write exists. Omit category to see the groups.

Call when you learn something standing about this work — who you are working with, how they want it done, what is being built, or where something lives. Kept until somebody removes it. Not for what went wrong: that is learning_note.

See which package scripts a workspace declares. Call before npm_script_run; only declared scripts can be run.

Run one declared package script. Use to verify a change with the project's own tests, checks or build before reporting it done. Arbitrary shell commands are not available, by design.

The whole persona: role, tagline, style prompt, voice values, traits, the pet's own mood lines, and whether the persona applies to agent replies or only to the pet. Call once per session and refresh only when the user says the pet or persona mode changed.

Show the user what you are doing. Use mood working when starting tool-based work, happy on success, idle when finished. Use error only for a real blocking failure. Returns only the resulting pet status; call pet_persona for the persona to speak in.

Which state the desktop pet is in right now — idle, working, happy, error or speaking — and its current message. Use to check what the user is seeing; call pet_persona for who the pet is.

Take one step, exclusively. Answers with the step, a working tree to do it in, and its resume — so nothing else has to be asked. Refused when somebody holds it, a gate is open, or a step in progress is touching the same files, and the refusal says which.

Call when a step is finished: it merges the working tree back and records what landed. Commit with a step trailer first — a step closed with nothing behind it is reported as a claim nobody can check. Closing as withdrawn merges nothing.

Open a plan: the ticket the work is tracked under, or a title when there is none. Call it when an investigation has settled on what to do and the doing needs steps — then break it down with step_add. Refused when the id is taken.

What a plan has for you to take right now, and why the rest is not available. Call this first in a session working from a plan — omit planId to see every plan at once. Never assume a step is free because it looks next.

Say you are still working. Call it during a long step — a claim nobody renews lapses, and the step is handed to somebody else while you are mid-edit.

What the plan says was done against what the repository shows. Use before trusting a plan you did not watch being executed, and after a session that ended badly.

Assemble canonical and working knowledge for one question, separated by authority, with open questions flagged by reference to the entry that holds them. Use instead of knowledge_search when you need grounded context to reason from rather than a result list. Omit both ids to use this endpoint's scope.

Who calls this symbol, with the call site. Use before changing a signature.

How much of the repository the last index rebuild actually re-read: files whose extraction changed, files reused from cache, and when it ran. Use after repo_index_refresh to see whether a change reached the index; use repo_index_status to learn whether a rebuild is needed at all.

One file as the index sees it: the symbols it declares in order, the files and packages it imports, and the files that import it. Use when you are about to read or change a file and want its place in the graph first; use repo_symbol_get for one symbol.

What breaks if this symbol changes, walked outward to a depth you choose. Use to size a change before making it.

Rebuild the repository index. Use when repo_index_status reports stale, or after changing files you then need to query.

Check whether a repository index exists and is current. Call before relying on any other repo_* tool.

Name the subsystems repo_unnamed_subsystems handed you: `names` maps each fingerprint to two to five plain words for what the group is about, never a symbol name you were shown and never the same name twice. Use once you have read enough to say. A refused name comes back with its reason, not as an error.

Everything directly connected to a symbol, in either direction. Use to explore outward. For "who calls this" specifically, repo_callers is narrower and cheaper.

Map a repository's subsystems and its most connected symbols. Call this first when you need to understand how a codebase is organised, before searching for individual symbols.

Every reference to a symbol, including ones the indexer could not resolve to an exact target. Use when repo_callers looks suspiciously short.

Every HTTP route (Express, NestJS, FastAPI, Flask, Spring, ASP.NET) and Electron IPC channel the index found, with handler, file and line. Use to find what handles an endpoint or channel; use repo_symbol_search when you know the handler's name.

Full detail for one symbol, with how many relationships point at it. Use after repo_symbol_search to confirm you have the right symbol before exploring it.

Find a symbol by name, signature, kind or path. Use instead of files_search when you are looking for a definition rather than arbitrary text. Test and fixture symbols are excluded unless includeTests is set.

The subsystems nobody has named yet, with a sample of each one's symbols. Unnamed, a group is called after its most connected symbol — in a large one a helper like `escapeHtml`, not the subject. Use after repo_index_refresh, or when repo_overview reads like a list of function names; answer with repo_name_subsystems.

Call when breaking a plan down, or when the work turns out to need one more piece. Adds a step: what it waits on, which files it touches, and the assignment in the words it was given. Size it to land as one commit — a step too big to commit is a step nothing can confirm.

Record what you did on a step before stopping. Call at the end of every stint, including one that failed — a stint missing from the history is indistinguishable from one that never happened.

One step in full: what was asked, where it stands, what is next, and what the last session actually touched. Call after taking one — a claim answers with this already, so this is for picking work back up.

Move a step on: its status, where it stands and what is next. Use at the end of a session that changed any of them, so the next one reads the state instead of inferring it.

Re-read a screenshot or other temporary asset by its resource URI, before it expires.

Create a vault directory. Rarely needed on its own — vault_file_create makes missing parents.

Create a new vault note, failing if it already exists. Use vault_file_write instead when replacing an existing note is intended.

Apply several line-range edits to one vault note in one call, all or none. Take the line numbers and expectedHash from vault_file_read; ranges refer to the note as you read it. Prefer this over vault_file_replace when you know where the change goes.

Set or remove frontmatter keys on a vault note without sending the body. Use for status, tags and updated; use vault_file_edit for the text itself.

Read one vault note, whole or a line range. Use when you already know the path; use knowledge_search when you do not.

Change known exact text in a vault note, one pair or several in one call. Use when you know the text but not the line, e.g. after knowledge_search; for changes at known lines use vault_file_edit.

Create or fully overwrite a vault note. Prefer vault_file_replace for edits — overwriting discards anything you did not include.

Browse one vault directory. Use when you want the shape of a folder; use vault_files_search to find a note anywhere in the vault, and knowledge_search to ask the vault a question.

Find a note anywhere in one vault by words in it. Reads every folder, which knowledge_search does not, and answers with the path, the line in the file and the text around it. Its index holds a vault's first 5,000 notes. Use it to locate a note; use knowledge_search to ask what the rule is.

Discover the knowledge vaults you may read and write, with their scope and access. Call this first when you do not already have a vaultId.

Show a vault or one note to the user in the Vault Viewer window. Use when the user should look at something; use vault_file_read when you need the content yourself.

What a vault holds: every folder, what belongs in each, how many notes and the most recent; read a note by its `recent[].path`, never by its title. Call it instead of walking folders, and after a search missed something. Measures what knowledge_search answers from: `indexedNotes` of `notes`, which can be 0 of 4.

Discover the repositories you may touch, with their project, organization and suggested vault. Call this first when you do not already have a workspaceId. Narrow it with organization, project or q instead of taking every workspace.