Skip to content
Documentation
Contents

Building tools

From a wish to a tool

The way from an idea to a released tool, in seven steps.

You do not build a tool by hand but together with an AI agent such as Claude Code. You describe what your organisation needs. The agent creates the data structure and writes the files of the tool. A person decides what reaches production.

Three terms

Collection: a collection is a set of data with fixed fields, for example a list of tasks. It can be extended, but nothing in it disappears again.

Tool: a tool is a small web page made of static files, which your instance serves at /t/<name>/. It reads and writes collections through the interface of the instance, with the permissions of the person using it.

Draft: the draft is the state of the tools that you and your agent work on. It is visible at /t/<name>@draft/, and only publishing turns it into the live state.

The way in steps

  1. Issue a token. The agent signs in under your name with a personal access token. Choose the practice room as its room. See Access tokens.
  2. Set up your workspace. One command clones the tool repository and registers the instance with your agent. See Setting up your workspace.
  3. Tell the agent what you need. Say which details the tool records, who uses it, what the data is for and how long your organisation keeps it. See Working with the agent.
  4. Collection and tool come into being. The collection is created in the practice room, the tool in the draft. Neither touches production. See Collections and fields and Layout of a tool.
  5. Check. Open the draft at /t/<name>@draft/ and try it with practice data. The agent uses check_tool to find out whether the state can be published. See Draft and publishing.
  6. Have it published. An administrator first carries the structure over from the practice room to production and then publishes the draft. See Carrying over from the practice room and Releasing tools.
  7. Grant permissions. Without a grant nobody sees the tool, and without a permission on the collection nobody sees data. Both belong to a role. See Granting permissions.

What to settle beforehand

Three things cannot be corrected later. Settle them before the agent starts:

  • Field names. A field that is in production stays. It can be renamed and deprecated, but not deleted.
  • Field types. A type can never be changed. A field that points to a person or to another collection needs the right type from the start.
  • Purpose and retention period. Every new collection states both. The agent asks you for them.

If you prefer to write it yourself

The agent is not mandatory. The tool repository is an ordinary Git repository, and the interface is HTTP with JSON. How to develop a tool on your own machine is described under Developing locally, the calls under Reading and writing data.