How Thomas Works

How commands run

Execution model

Every request goes through planning, policy gates, and audit tracing before anything runs.

Coverage

Contract status: 32 implemented / 21 declared Total command families: 53

Last validated: 3/2/2026, 1:09:04 AM

What we track

Families with explicit command depth
Coverage and evidence status per family
Route/path traceability for execution artifacts

Execution pipeline

pipeline

user request -> policy + trust gate -> plan generation -> tool execution + hook sequence -> result validation -> audit log -> response returned to caller

Command family matrix

Source for command families:

32 implemented / 21 declared

Total command count: 400

Last validated snapshot: 3/2/2026, 1:09:04 AM

Showing 53 of 53 families.

Command matrix controlsSearch, filter, and view mode

Search families / commands

/acp

Implemented

Depth 2Commands 2

/agent

Declared

Depth 0Commands 0

/agents

Implemented

Depth 4Commands 4

/approvals

Implemented

Depth 10Commands 10

/browser

Implemented

Depth 45Commands 45

/channels

Implemented

Depth 31Commands 31

/chat

Declared

Depth 0Commands 0

/clawbot

Implemented

Depth 2Commands 2

/codex

Implemented

Depth 4Commands 4

/companion

Implemented

Depth 8Commands 8

/completion

Declared

Depth 0Commands 0

/config

Implemented

Depth 4Commands 4

/configure

Declared

Depth 0Commands 0

/cron

Implemented

Depth 16Commands 16

/daemon

Implemented

Depth 7Commands 7

/dashboard

Declared

Depth 0Commands 0

/devices

Implemented

Depth 11Commands 11

/directory

Implemented

Depth 9Commands 9

/dns

Implemented

Depth 2Commands 2

/docs

Declared

Depth 0Commands 0

/doctor

Declared

Depth 0Commands 0

/doppelganger

Implemented

Depth 6Commands 6

/gateway

Implemented

Depth 36Commands 36

/health

Declared

Depth 0Commands 0

/hooks

Implemented

Depth 7Commands 7

/library

Implemented

Depth 6Commands 6

/live-browser-smoke

Declared

Depth 0Commands 0

/logs

Declared

Depth 0Commands 0

/memory

Implemented

Depth 10Commands 10

/message

Implemented

Depth 29Commands 29

/models

Implemented

Depth 12Commands 12

/node

Implemented

Depth 17Commands 17

/nodes

Implemented

Depth 24Commands 24

/onboard

Declared

Depth 0Commands 0

/pairing

Implemented

Depth 9Commands 9

/plugins

Implemented

Depth 39Commands 39

/qr

Declared

Depth 0Commands 0

/repl

Declared

Depth 0Commands 0

/reset

Declared

Depth 0Commands 0

/sandbox

Implemented

Depth 3Commands 3

/security

Implemented

Depth 8Commands 8

/serve

Declared

Depth 0Commands 0

/sessions

Declared

Depth 0Commands 0

/setup

Declared

Depth 0Commands 0

/skills

Implemented

Depth 9Commands 9

/status

Declared

Depth 0Commands 0

/system

Implemented

Depth 10Commands 10

/telegram

Implemented

Depth 1Commands 1

/tools

Declared

Depth 0Commands 0

/tui

Declared

Depth 0Commands 0

/uninstall

Declared

Depth 0Commands 0

/update

Implemented

Depth 8Commands 8

/webhooks

Implemented

Depth 11Commands 11

Integrity evidence

Audit log example23 events processed - 214ms total

integrity-audit

{
  "requestId": "rq-2026-03-02-001",
  "timestamp": "2026-03-02T01:09:04Z",
  "route": "/v1/chat/completions",
  "policy": "approved",
  "commandFamily": "/status",
  "result": "ok",
  "elapsedMs": 214,
  "hooks": [
    "before-model",
    "before-tool",
    "after-tool",
    "after-response"
  ],
  "trace": [
    "/api-gateway",
    "/planner",
    "/hooks",
    "/tool",
    "/validation",
    "/audit-log"
  ],
  "logFile": "/var/log/thomas/events.jsonl"
}

Execution JSON example6 steps with schema checks

integrity-execution-json

{
  "userPrompt": "List repository status",
  "plan": {
    "family": "status",
    "command": "status",
    "policyGate": "ok",
    "approvalState": "required"
  },
  "execution": {
    "output": {
      "totalSteps": 6,
      "exitCode": 0
    },
    "checks": {
      "schemaValidation": true,
      "policyGate": true,
      "commandContract": true
    }
  },
  "artifacts": {
    "auditId": "rq-2026-03-02-001",
    "artifactPath": "/var/log/thomas/events.jsonl"
  }
}

Flow artifactExecution artifact path and route path

integrity-flow

user request -> policy + trust gate -> plan generation -> tool execution + hook sequence -> result validation -> audit log -> response returned to caller

Gateway parity evidenceHTTP and CLI route contract parity

integrity-gateway-parity

thomas prompt "status"
thomas ask "List repository status"
thomas --help --json

Gateway contracts and CLI parity

Non-stream request example

curl request

curl -X POST https://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <local-token>" \
  -d '{\n  "model": "local-gpt",\n  "messages": [{"role": "user", "content": "List repository status"}],\n  "stream": false\n}'

Streaming event model

sse events

event: response.started
data: {"id":"evt-01","type":"response.started","request_id":"rq-2026-03-02-001"}

event: tool.delta
data: {"id":"evt-01","type":"tool.delta","tool":"status","payload":{"phase":"running"}}

event: response.final
data: {"id":"evt-01","type":"response.final","status":"ok","request_id":"rq-2026-03-02-001"}

Non-stream response format

response.json

{
  "id": "cmp-102",
  "status": "ok",
  "model": "local-gpt",
  "request_id": "rq-2026-03-02-001",
  "usage": {
    "prompt_tokens": 14,
    "completion_tokens": 32
  }
}

CLI parity check

CLI commands

thomas prompt "status"
thomas ask "List repository status"
thomas --help --json

Plugin execution boundary

Hook execution architecture

plugin architecture

client
  |-- parser + policy gate
  |-- command planner
  |-- execution runtime
  \-- audit sink
      |-- before-model hooks
      |-- before-tool hooks
      |-- tool.exec hooks
      |-- after-tool hooks
      \-- after-response hooks

Lifecycle

Install package

Validate manifest and checksum

Activate in registry

Execute through protected path

Deactivate + remove runtime state

Uninstall package

Manifest example

plugin-manifest.json

{
  "name": "thomas-plugin-guard",
  "version": "0.1.0",
  "entry": "dist/index.js",
  "permissions": ["filesystem", "network:thomas-control"],
  "hooks": [
    "before-model",
    "before-tool",
    "after-tool",
    "after-response"
  ]
}

Install -> validate -> activate -> execute

plugin lifecycle commands

thomas plugin install ./dist/thomas-plugin-guard.zip
thomas plugin validate thomas-plugin-guard
thomas plugin activate thomas-plugin-guard
thomas plugin run thomas-plugin-guard --diagnostic
thomas plugin deactivate thomas-plugin-guard
thomas plugin uninstall thomas-plugin-guard

What's next

Not planned: Unbounded autonomous execution.
Not planned: Claims of universal API coverage without route evidence.
Not planned: Implicit trust without policy gates.

Command evidence snapshots

Implemented

Row-level coverage metadata is present for families and linked to source artifacts.

Gateway contract coverage

Implemented

HTTP contracts and CLI calls share the same guard and validation surface.

Plugin lifecycle replay

Declared

Next up: full install + policy-hook replay with trace replayability.

Loading state

{ "requestId": "rq-2026-03-02-001", "timestamp": "2026-03-02T01:09:04Z", "route": "/v1/chat/completions", "policy": "approved", "commandFamily": "/status", "result": "ok", "elapsedMs": 214, "hooks": [ "before-model", "before-tool", "after-tool", "after-response" ], "trace": [ "/api-gateway", "/planner", "/hooks", "/tool", "/validation", "/audit-log" ], "logFile": "/var/log/thomas/events.jsonl" }

{ "userPrompt": "List repository status", "plan": { "family": "status", "command": "status", "policyGate": "ok", "approvalState": "required" }, "execution": { "output": { "totalSteps": 6, "exitCode": 0 }, "checks": { "schemaValidation": true, "policyGate": true, "commandContract": true } }, "artifacts": { "auditId": "rq-2026-03-02-001", "artifactPath": "/var/log/thomas/events.jsonl" } }

curl -X POST https://127.0.0.1:8787/v1/chat/completions \ -H "Content-Type: application/json" \ -H "Authorization: Bearer <local-token>" \ -d '{\n "model": "local-gpt",\n "messages": [{"role": "user", "content": "List repository status"}],\n "stream": false\n}'

event: response.started data: {"id":"evt-01","type":"response.started","request_id":"rq-2026-03-02-001"} event: tool.delta data: {"id":"evt-01","type":"tool.delta","tool":"status","payload":{"phase":"running"}} event: response.final data: {"id":"evt-01","type":"response.final","status":"ok","request_id":"rq-2026-03-02-001"}

{ "name": "thomas-plugin-guard", "version": "0.1.0", "entry": "dist/index.js", "permissions": ["filesystem", "network:thomas-control"], "hooks": [ "before-model", "before-tool", "after-tool", "after-response" ] }

thomas plugin install ./dist/thomas-plugin-guard.zip thomas plugin validate thomas-plugin-guard thomas plugin activate thomas-plugin-guard thomas plugin run thomas-plugin-guard --diagnostic thomas plugin deactivate thomas-plugin-guard thomas plugin uninstall thomas-plugin-guard