AI coding tools such as Claude Code can create, debug, and update TrakHound modules from a description of what you need. The Framework gives these tools a well-defined target: every module starts from a template, inherits a base class, has one responsibility, and uses the same interfaces for data, settings, and logging. The Instance handles hosting, security, routing, and deployment, so generated code only needs to contain the logic for your process.
dotnet new adds AGENTS.mddotnet run; the tool fixes its own errorsWhy It Works Well
- Templates - Each module type has a template with the correct base class, manifest, and project setup, so the AI tool starts from a working project
- Small modules - An App, API, Function, or Worker does one thing, keeping each request and each change small enough to review
- Common interfaces - Data is read and written through Services, so generated code does not need connection strings, credentials, or database specific code
- Local debugging - Modules run with
dotnet runagainst a local Instance, and unit tests run them without one, so the AI tool can build, run, test, and fix its own errors - Packages - Finished modules are versioned Packages, so AI-built tools follow the same review, deployment, and change control as everything else
1. Create the Project from a Template
Start every module from a template instead of asking the AI tool to create the project. The template sets up the base class, the trakhound.package.json manifest,
the Program.cs used for local debugging, and instructions for AI coding tools:
dotnet new trakhound.app -n MachineStatus
cd MachineStatus
See Quick Start to install the templates and build your first module.
2. Review the Project Instructions
AI coding tools read an instructions file in the project folder to learn its conventions. Every template creates an AGENTS.md, read by most AI coding tools,
and a CLAUDE.md that imports it for Claude Code. It lists the commands to build, run, and publish the module, its files, and the rules for writing that kind of Package,
such as reading data only through Client.Services, not hard coding paths or credentials, and describing API parameters.
Edit it as the module grows, adding what is specific to your module, such as the Services and collections it uses and what belongs in other modules:
## This Module
- Show machine status only. Put data collection in a Worker and processing in a Function
instead of adding it here.
- Machine status is in the 'machines' Key-Value collection, keyed by machine ID.
- Do not change trakhound.package.json unless asked.
For a repository with several modules, put an AGENTS.md at its root as well. Point the AI tool at these docs for details, for example the
Apps and Services pages.
3. Describe the Module
Describe what the module should do in terms of TrakHound concepts: which Services it reads and writes, which Functions or APIs it calls, and what it displays or returns.
claude "Create a page that lists every machine in the 'machines' Key-Value collection
with its current status. Refresh every 5 seconds and show Running in green and
Stopped in red."
Example requests for each module type:
| Module | Example Request |
|---|---|
| App | Create a page that shows open work orders from the work_orders Table, with a filter by machine. |
| API | Add a GET endpoint that returns the status of a machine from the machines Key-Value collection, and a PUT endpoint that updates it. |
| Function | Create a Function that reads yesterday's part counts from the parts Table and writes a daily summary PDF to the reports Blob collection. |
| Worker | Create a Worker that subscribes to machines/+/status Messages and stores the latest status of each machine in the machines Key-Value collection. |
| Identity | Create an Identity provider that authenticates requests using a token stored in the Identity configuration parameters. |
4. Run and Debug Locally
Ask the AI tool to build and run the project with dotnet run. The module connects to the local Instance at localhost:8472,
so the tool can see build errors and runtime logs and fix them before you review the result.
Use the Explorer and Diagnostics pages in the Instance's admin UI to check data, API requests, and logs.
To try the module inside the Instance with its routing and security, run th dev run, which reinstalls it each time the tool saves a change.
Ask the tool to add unit tests with TrakHound.Testing too, so it can check its own changes with dotnet test.
See Debugging & Testing.
5. Review the Changes
Review generated code the same way you would review code from a new team member:
- Keep each request small (one page, one endpoint, or one Function at a time) so each change is easy to read
- Check that data is accessed only through
Client.Services, and that no paths, URLs, or credentials are hard coded - Check that the module still has a single responsibility, and split it into separate modules if it has grown
- Commit to source control after each working step so changes can be compared and undone
6. Package, Publish, and Install
Build the module into a versioned Package and install it on an Instance:
th packages dotnet --publish
th packages install MachineStatus
Then create a configuration for the Package in the admin UI. Because every Package is versioned, a previous version can be reinstalled with
th packages install <packageId> --version <version>. See Packages and the CLI.
Install new versions on a test Instance first so process engineers can try them before they reach production. See Development, Test & Production.
Building Larger Applications
Split a larger application into several modules and build them one at a time, for example a Worker that collects data, a Function that processes it,
an API that exposes it, and an App that displays it. Modules share data through Services and call each other with Client.Functions.Run and API requests,
so each one can be generated, reviewed, and updated on its own. Engineers from different teams can build their own modules with AI tools and still run them on the same Instance.
Security and Regulated Environments
- AI coding tools send prompts and code to the tool's provider. Check your organization's policies before using them with sensitive, export controlled, or regulated code and data.
- The AI tool is only used during development. The modules you build, and the data they work with, run on your own Instances.
- Modules do not need database or message broker credentials. These are set by IT in Service configurations on the Instance (see Services), so the AI tool never sees them.
- Never give an AI tool production credentials or paste them into prompts or instructions files.
- Identity modules and security profiles apply to AI-built modules the same as any other module.
- Add new modules to a Zone in Audit mode to see exactly which APIs, Functions, Services, and Volumes they reach, then switch to Enforce so they can't reach anything else by accident.
- A Zone's Service Router can send every Service call a module makes to test data while it is being tried on a shared Instance.
Connecting AI Assistants to an Instance
This page covers using AI tools to build modules. To give AI assistants access to the data and Functions in an Instance, turn on the Instance's built-in MCP Server. AI clients such as Claude can then list and run Functions, read Logs, query Tables, and read Key-Values and Messages, limited by the same security profiles and API keys as everything else.
To let AI assistants use your own module, ask the AI tool to mark the API endpoints that are safe for an agent to call with [ApiMcpTool]
and to describe their parameters. See APIs.
AI coding tools building applications on an Instance's APIs can read its /llms.txt, a Markdown index of the APIs they can use, with links to each OpenAPI document.
A module that runs code an AI tool wrote in another language (ex. a Python script) can give that process a Module Token, so its calls are made as the module and its Zone still applies.