go-ai/docs/tools.md

go-ai MCP Tool Reference

Module: forge.lthn.ai/core/go-ai

This document is the authoritative reference for every MCP tool exposed by the go-ai hub. It is generated from the source definitions in mcp/ and mcp/ide/.

---

Overview

go-ai exposes 49 tools across 13 functional groups via the Model Context Protocol. The server can be started in two modes:

• Stdio (default): core mcp serve — standard MCP transport for use with Claude, Cursor, and other MCP clients.
• TCP: MCP_ADDR=:9000 core mcp serve — listens on a TCP socket for programmatic access.

Registration model

Tools are registered in two tiers:

1. Built-in tools (registered unconditionally in mcp.New()): file operations, directory operations, language detection, RAG, metrics, and webview tools. These are always present regardless of configuration.

2. Subsystem tools (registered via WithSubsystem()): ML, process management, WebSocket, and IDE tools. These require the corresponding backend service to be provided via an Option at construction time. Process and WebSocket tools are silently omitted if their respective services are not supplied. IDE tools are provided by the ide.Subsystem subsystem.

Workspace sandboxing

All file and directory tools operate within a sandboxed filesystem medium. By default the sandbox root is the current working directory at the time mcp.New() is called. The root can be changed with WithWorkspaceRoot(path). All paths supplied to file tools are validated to remain within this root — path traversal attempts are rejected.

Audit logging

Every tool execution is logged. Tools that perform writes, process control, or browser automation are logged at Security level. Read-only tools are logged at Info level.

---

Tool Groups

Group	Tools	File
File Operations	6	mcp/mcp.go
Directory Operations	2	mcp/mcp.go
Language Detection	2	mcp/mcp.go
RAG — Vector Search	3	mcp/tools_rag.go
ML — Inference & Scoring	5	mcp/tools_ml.go
Metrics	2	mcp/tools_metrics.go
Process Management	6	mcp/tools_process.go
WebSocket	2	mcp/tools_ws.go
Browser Automation	10	mcp/tools_webview.go
IDE Chat	5	mcp/ide/tools_chat.go
IDE Build	3	mcp/ide/tools_build.go
IDE Dashboard	3	mcp/ide/tools_dashboard.go

---

File Operations

Six tools for reading, writing, editing, renaming, deleting, and checking files. All paths are resolved relative to the configured workspace root and must not escape it.

---

file_read

Read the contents of a file.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Path to the file, relative to workspace root

Response

Field	Type	JSON key	Description
Content	string	content	Full file contents
Language	string	language	Detected language ID (see lang_detect)
Path	string	path	Echoed input path

Notes

The language field is populated by extension-based detection and will be "plaintext" for unrecognised extensions. The call fails if the path does not exist or points outside the workspace root.

---

file_write

Write content to a file, creating it and any intermediate directories if they do not exist.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Destination path, relative to workspace root
Content	string	content	Yes	Content to write

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the write succeeded
Path	string	path	Echoed input path

Notes

Overwrites any existing file at the given path without warning. Parent directories are created automatically. Logged at Security level.

---

file_edit

Edit a file by replacing one occurrence (or all occurrences) of old_string with new_string. The file must already exist.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Path to the file
OldString	string	old_string	Yes	Exact string to find; must not be empty
NewString	string	new_string	Yes	Replacement string (may be empty to delete)
ReplaceAll	bool	replace_all	No	Replace every occurrence; default is first only

Response

Field	Type	JSON key	Description
Path	string	path	Echoed input path
Success	bool	success	Whether the edit succeeded
Replacements	int	replacements	Number of occurrences replaced

Notes

Returns an error if old_string is empty or is not found in the file. With replace_all=false (default) only the first occurrence is replaced and replacements will be 1. With replace_all=true all occurrences are replaced and replacements reflects the total count.

---

file_delete

Delete a file or empty directory.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Path to delete

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the deletion succeeded
Path	string	path	Echoed input path

Notes

Non-empty directories are not deleted; use multiple calls or a process tool to remove them recursively. Logged at Security level.

---

file_rename

Rename or move a file within the workspace.

Parameters

Field	Type	JSON key	Required	Description
OldPath	string	oldPath	Yes	Current path
NewPath	string	newPath	Yes	Destination path

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the rename succeeded
OldPath	string	oldPath	Echoed source path
NewPath	string	newPath	Echoed destination path

Notes

Both paths must remain within the workspace root. Can be used to move files between subdirectories. Logged at Security level.

---

file_exists

Check whether a path exists and whether it is a file or directory.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Path to check

Response

Field	Type	JSON key	Description
Exists	bool	exists	Whether the path exists
IsDir	bool	isDir	Whether the path is a directory
Path	string	path	Echoed input path

Notes

Returns exists=false for paths that do not exist or are inaccessible. Does not distinguish between a missing path and a permission error.

---

Directory Operations

Two tools for listing and creating directories within the workspace.

---

dir_list

List the contents of a directory.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Directory path, relative to workspace root

Response

Field	Type	JSON key	Description
Entries	[]DirectoryEntry	entries	List of entries
Path	string	path	Echoed input path

DirectoryEntry fields

Field	Type	JSON key	Description
Name	string	name	Entry name (filename only)
Path	string	path	Entry path (joined with input path)
IsDir	bool	isDir	Whether the entry is a directory
Size	int64	size	File size in bytes; 0 for directories

Notes

Lists only the immediate children; not recursive. The path field in each entry preserves the relative form of the input path.

---

dir_create

Create a new directory, including any necessary parent directories.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	Directory path to create

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the directory was created
Path	string	path	Echoed input path

Notes

Behaves like mkdir -p; does not fail if the directory already exists.

---

Language Detection

Two tools for working with the built-in language registry.

---

lang_detect

Detect the programming language of a file based on its extension or name.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	File path (the file need not exist; only the name is inspected)

Response

Field	Type	JSON key	Description
Language	string	language	Detected language ID
Path	string	path	Echoed input path

Notes

Detection is purely extension-based. Dockerfile (exact name, no extension) is detected as "dockerfile". Unknown extensions return "plaintext".

---

lang_list

Get the list of all supported programming languages.

Parameters

None.

Response

Field	Type	JSON key	Description
Languages	[]LanguageInfo	languages	All supported language entries

LanguageInfo fields

Field	Type	JSON key	Description
ID	string	id	Language identifier used throughout the API
Name	string	name	Human-readable display name
Extensions	[]string	extensions	File extensions that map to this language

Supported languages

typescript, javascript, go, python, rust, java, php, ruby, html, css, json, yaml, markdown, sql, shell

The full detection set (including c, cpp, csharp, scss, xml, swift, kotlin, dockerfile) is available via lang_detect but is not enumerated by lang_list.

---

RAG — Vector Search

Three tools for semantic document retrieval and ingestion. These tools require:

• Qdrant running at localhost:6334 (default gRPC port)
• Ollama running at localhost:11434 for embedding generation

The default collection name is hostuk-docs.

---

rag_query

Query the RAG vector database for relevant documentation. Returns semantically similar content based on the query.

Parameters

Field	Type	JSON key	Required	Description
Question	string	question	Yes	The natural-language query
Collection	string	collection	No	Collection name; default hostuk-docs
TopK	int	topK	No	Number of results to return; default 5

Response

Field	Type	JSON key	Description
Results	[]RAGQueryResult	results	Ordered list of matching chunks
Query	string	query	Echoed question
Collection	string	collection	Collection used
Context	string	context	Pre-formatted context string suitable for injection into a prompt

RAGQueryResult fields

Field	Type	JSON key	Description
Content	string	content	The chunk text
Source	string	source	Original source file or URL
Section	string	section	Section heading within the source (if available)
Category	string	category	Category tag (if available)
ChunkIndex	int	chunkIndex	Chunk position within the source document
Score	float32	score	Cosine similarity score

Notes

Returns an error if question is empty. Results are ordered by descending similarity score. The context field is ready for direct use in a system prompt.

---

rag_ingest

Ingest documents into the RAG vector database. Supports both single files and entire directories.

Parameters

Field	Type	JSON key	Required	Description
Path	string	path	Yes	File or directory path to ingest
Collection	string	collection	No	Target collection; default hostuk-docs
Recreate	bool	recreate	No	Drop and recreate the collection before ingestion

Response

Field	Type	JSON key	Description
Success	bool	success	Whether ingestion succeeded
Path	string	path	Echoed input path
Collection	string	collection	Collection used
Chunks	int	chunks	Number of chunks indexed (file only; 0 for directory)
Message	string	message	Human-readable summary

Notes

The path is validated against the workspace medium (sandboxed). For directory ingestion the chunk count is not returned. Setting recreate=true destroys all existing vectors in the collection before ingesting. Logged at Security level.

---

rag_collections

List all available collections in the Qdrant vector database.

Parameters

Field	Type	JSON key	Required	Description
ShowStats	bool	show_stats	No	Include point count and status for each collection

Response

Field	Type	JSON key	Description
Collections	[]CollectionInfo	collections	List of collections

CollectionInfo fields

Field	Type	JSON key	Description
Name	string	name	Collection name
PointsCount	uint64	points_count	Total vectors stored (only present when show_stats=true)
Status	string	status	Qdrant collection status (only present when show_stats=true)

Notes

Opens a short-lived Qdrant client connection per call. Stats are fetched per-collection and failures for individual collections are logged and skipped rather than aborting the entire response.

---

ML — Inference & Scoring

Five tools for text generation, response scoring, capability probing, pipeline status, and backend enumeration. These tools are provided by the MLSubsystem and require a configured go-ml service instance (ml.Service).

The generation path is: go-ai → go-ml.Service.Generate → InferenceAdapter → inference.TextModel (from go-inference).

---

ml_generate

Generate text via a configured ML inference backend.

Parameters

Field	Type	JSON key	Required	Description
Prompt	string	prompt	Yes	The input prompt
Backend	string	backend	No	Backend name; uses service default if omitted
Model	string	model	No	Model override for backends that support multiple models
Temperature	float64	temperature	No	Sampling temperature
MaxTokens	int	max_tokens	No	Maximum tokens to generate

Response

Field	Type	JSON key	Description
Response	string	response	Generated text
Backend	string	backend	Backend used
Model	string	model	Model used (if applicable)

Notes

Returns an error if prompt is empty. Backend selection falls through to the service default when backend is not specified. Available backends can be queried with ml_backends.

---

ml_score

Score a prompt/response pair using one or more scoring suites.

Parameters

Field	Type	JSON key	Required	Description
Prompt	string	prompt	Yes	The original prompt
Response	string	response	Yes	The model response to evaluate
Suites	string	suites	No	Comma-separated suite names; default heuristic

Available suites: heuristic, semantic

Response

Field	Type	JSON key	Description
Heuristic	*ml.HeuristicScores	heuristic	Length, structure, and format heuristics (present when requested)
Semantic	*ml.SemanticScores	semantic	LLM judge scores (present when requested)
Content	*ml.ContentScores	content	Content scores (not available via this tool; use ml_probe)

Notes

heuristic scoring requires no backend. semantic scoring requires a judge backend to be configured in the ML service; the call returns an error if none is present. The content suite is not supported by this tool — use ml_probe instead. Both prompt and response must be non-empty.

---

ml_probe

Run capability probes against an inference backend. Each probe sends a structured prompt to the backend and records the response.

Parameters

Field	Type	JSON key	Required	Description
Backend	string	backend	No	Backend name; uses service default if omitted
Categories	string	categories	No	Comma-separated category names to filter probes; all categories run if omitted

Response

Field	Type	JSON key	Description
Total	int	total	Number of probes executed
Results	[]MLProbeResultItem	results	Per-probe results

MLProbeResultItem fields

Field	Type	JSON key	Description
ID	string	id	Probe identifier
Category	string	category	Probe category
Response	string	response	Backend response, or an error string prefixed with "error: "

Notes

Probes are drawn from ml.CapabilityProbes defined in go-ml. Individual probe failures are captured as error strings in the response rather than aborting the entire run. Temperature is fixed at 0.7 and MaxTokens at 2048 for all probes.

---

ml_status

Show training and generation progress from InfluxDB.

Parameters

Field	Type	JSON key	Required	Description
InfluxURL	string	influx_url	No	InfluxDB URL; default http://localhost:8086
InfluxDB	string	influx_db	No	Database name; default lem

Response

Field	Type	JSON key	Description
Status	string	status	Formatted status report as a multi-line string

Notes

Connects to InfluxDB on each call. Returns an error if the InfluxDB instance is unreachable.

---

ml_backends

List available inference backends and their status.

Parameters

None.

Response

Field	Type	JSON key	Description
Backends	[]MLBackendInfo	backends	All registered backends
Default	string	default	Name of the default backend

MLBackendInfo fields

Field	Type	JSON key	Description
Name	string	name	Backend identifier
Available	bool	available	Whether the backend is currently available

Notes

Queries the go-inference global registry directly, bypassing go-ml.Service. This is the canonical source of truth for which backends are compiled in and available at runtime.

---

Metrics

Two tools for recording and querying agent activity events. Events are stored in daily JSONL files on the local filesystem via the go-ai/ai package.

---

metrics_record

Record a metrics event for AI or security tracking.

Parameters

Field	Type	JSON key	Required	Description
Type	string	type	Yes	Event type identifier
AgentID	string	agent_id	No	Agent identifier
Repo	string	repo	No	Repository name associated with the event
Data	map[string]any	data	No	Arbitrary additional event data

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the event was recorded
Timestamp	time.Time	timestamp	Server-assigned event timestamp

Notes

The timestamp is assigned by the server at the moment of recording; any timestamp in data is treated as user data only. Returns an error if type is empty.

---

metrics_query

Query metrics events and get aggregated statistics by type, repository, and agent.

Parameters

Field	Type	JSON key	Required	Description
Since	string	since	No	Lookback window; default 7d

Supported duration formats: Nd (days), Nh (hours), Nm (minutes). Examples: "7d", "24h", "30m".

Response

Field	Type	JSON key	Description
Total	int	total	Total events in window
ByType	[]MetricCount	by_type	Event counts grouped by type
ByRepo	[]MetricCount	by_repo	Event counts grouped by repository
ByAgent	[]MetricCount	by_agent	Event counts grouped by agent ID
Events	[]MetricEventBrief	events	The 10 most recent events, newest first

MetricCount fields

Field	Type	JSON key	Description
Key	string	key	Group key (type name, repo name, or agent ID)
Count	int	count	Number of events in this group

MetricEventBrief fields

Field	Type	JSON key	Description
Type	string	type	Event type
Timestamp	time.Time	timestamp	Event timestamp
AgentID	string	agent_id	Agent identifier (if set)
Repo	string	repo	Repository name (if set)

Notes

Returns an error if the since value cannot be parsed. The duration unit must be a single character: d, h, or m. Durations must be positive integers.

---

Process Management

Six tools for starting, stopping, and interacting with external processes. These tools are only registered when a process.Service instance is provided via WithProcessService() at construction time.

All process-control operations (process_start, process_stop, process_kill, process_input) are logged at Security level.

---

process_start

Start a new external process. Returns a process ID for tracking.

Parameters

Field	Type	JSON key	Required	Description
Command	string	command	Yes	The executable to run
Args	[]string	args	No	Command-line arguments
Dir	string	dir	No	Working directory for the process
Env	[]string	env	No	Additional environment variables in KEY=VALUE format

Response

Field	Type	JSON key	Description
ID	string	id	Unique process identifier used in subsequent calls
PID	int	pid	Operating system process ID
Command	string	command	Echoed command
Args	[]string	args	Echoed arguments
StartedAt	time.Time	startedAt	Process start time

Notes

Returns an error if command is empty. The process is managed by the process.Service; its output is captured and available via process_output.

---

process_stop

Gracefully stop a running process by ID.

Parameters

Field	Type	JSON key	Required	Description
ID	string	id	Yes	Process ID returned by process_start

Response

Field	Type	JSON key	Description
ID	string	id	Echoed process ID
Success	bool	success	Whether the stop signal was sent
Message	string	message	Status message

Notes

The current implementation sends SIGKILL. A SIGTERM-first approach may be introduced in a future version. If the process does not respond, use process_kill.

---

process_kill

Force kill a process by ID.

Parameters

Field	Type	JSON key	Required	Description
ID	string	id	Yes	Process ID returned by process_start

Response

Field	Type	JSON key	Description
ID	string	id	Echoed process ID
Success	bool	success	Whether the kill succeeded
Message	string	message	Status message

Notes

Sends an unconditional kill signal via process.Service.Kill(). Use when process_stop does not succeed within an acceptable time.

---

process_list

List all managed processes.

Parameters

Field	Type	JSON key	Required	Description
RunningOnly	bool	running_only	No	Return only actively running processes; default false

Response

Field	Type	JSON key	Description
Processes	[]ProcessInfo	processes	List of process records
Total	int	total	Number of records returned

ProcessInfo fields

Field	Type	JSON key	Description
ID	string	id	Process identifier
Command	string	command	Executable name
Args	[]string	args	Arguments
Dir	string	dir	Working directory
Status	string	status	Process status string
PID	int	pid	OS process ID
ExitCode	int	exitCode	Exit code (meaningful only after termination)
StartedAt	time.Time	startedAt	Process start time
Duration	time.Duration	duration	Elapsed or total runtime

---

process_output

Get the captured stdout/stderr output of a process by ID.

Parameters

Field	Type	JSON key	Required	Description
ID	string	id	Yes	Process ID

Response

Field	Type	JSON key	Description
ID	string	id	Echoed process ID
Output	string	output	Captured output as a single string

Notes

Output is buffered by process.Service. For streaming output in real time, connect a WebSocket subscriber via ws_start and subscribe to the process channel.

---

process_input

Send text to the stdin of a running process.

Parameters

Field	Type	JSON key	Required	Description
ID	string	id	Yes	Process ID
Input	string	input	Yes	Text to write to stdin

Response

Field	Type	JSON key	Description
ID	string	id	Echoed process ID
Success	bool	success	Whether the input was delivered
Message	string	message	Status message

Notes

Returns an error if the process is not found or if input is empty. Does not append a newline automatically; include "\n" in input if required.

---

WebSocket

Two tools for starting and inspecting the WebSocket hub used for real-time process output streaming. These tools are only registered when a ws.Hub instance is provided via WithWSHub() at construction time.

The WebSocket endpoint is served at /ws on the configured address.

---

ws_start

Start the WebSocket server for real-time process output streaming.

Parameters

Field	Type	JSON key	Required	Description
Addr	string	addr	No	Listen address in host:port format; default ":8080"

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the server started (or was already running)
Addr	string	addr	Actual address the server is bound to
Message	string	message	Status message including the full WebSocket URL

Notes

If the server is already running, returns the existing address without error. The WebSocket URL takes the form ws://<addr>/ws. Logged at Security level because it opens a network listener.

---

ws_info

Get WebSocket hub statistics.

Parameters

None.

Response

Field	Type	JSON key	Description
Clients	int	clients	Number of currently connected WebSocket clients
Channels	int	channels	Number of active subscription channels

---

Browser Automation

Ten tools for controlling a Chrome browser via the Chrome DevTools Protocol (CDP). All browser tools share a single global webview.Webview instance; webview_connect must be called before any other browser tool in a session.

Prerequisite: start Chrome with remote debugging enabled:

google-chrome --remote-debugging-port=9222

webview_connect, webview_eval, and webview_navigate are logged at Security level due to their capability to exfiltrate data or execute arbitrary code.

---

webview_connect

Connect to a running Chrome instance via the Chrome DevTools Protocol.

Parameters

Field	Type	JSON key	Required	Description
DebugURL	string	debug_url	Yes	Chrome DevTools URL, e.g. http://localhost:9222
Timeout	int	timeout	No	Default operation timeout in seconds; default 30

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the connection was established
Message	string	message	Status message

Notes

Closes any existing connection before establishing a new one. Returns an error if debug_url is empty or if Chrome is not reachable at the given address.

---

webview_disconnect

Disconnect from Chrome DevTools and release the connection.

Parameters

None.

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the disconnection succeeded
Message	string	message	Status message

Notes

Returns success=true with message "No active connection" if no connection was open. Safe to call multiple times.

---

webview_navigate

Navigate the browser to a URL.

Parameters

Field	Type	JSON key	Required	Description
URL	string	url	Yes	Fully qualified URL to navigate to

Response

Field	Type	JSON key	Description
Success	bool	success	Whether navigation was initiated
URL	string	url	Echoed URL

Notes

Returns an error if not connected. Navigation is initiated but this tool does not wait for the page to finish loading; use webview_wait to synchronise on a page element after navigation.

---

webview_click

Click on an element identified by a CSS selector.

Parameters

Field	Type	JSON key	Required	Description
Selector	string	selector	Yes	CSS selector for the target element

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the click was performed

Notes

Returns an error if not connected or if selector is empty. The selector must match at least one element; the first match is clicked.

---

webview_type

Type text into an element identified by a CSS selector.

Parameters

Field	Type	JSON key	Required	Description
Selector	string	selector	Yes	CSS selector for the target element
Text	string	text	Yes	Text to type into the element

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the text was typed

Notes

Returns an error if not connected or if selector is empty. Appends to any existing content in the element rather than replacing it; clear the field first if a fresh value is required.

---

webview_query

Query DOM elements by CSS selector.

Parameters

Field	Type	JSON key	Required	Description
Selector	string	selector	Yes	CSS selector
All	bool	all	No	Return all matching elements; default returns first match only

Response

Field	Type	JSON key	Description
Found	bool	found	Whether any elements matched
Count	int	count	Number of elements matched
Elements	[]WebviewElementInfo	elements	Element details

WebviewElementInfo fields

Field	Type	JSON key	Description
NodeID	int	nodeId	CDP node identifier
TagName	string	tagName	HTML tag name
Attributes	map[string]string	attributes	Element attributes
BoundingBox	*webview.BoundingBox	boundingBox	Element position and dimensions

Notes

With all=false (default), returns at most one element and found=false when no match exists. With all=true, returns all matches. A zero-result all=true query returns found=false and an empty slice rather than an error.

---

webview_console

Get browser console messages captured since the last call.

Parameters

Field	Type	JSON key	Required	Description
Clear	bool	clear	No	Clear the console buffer after reading; default false

Response

Field	Type	JSON key	Description
Messages	[]WebviewConsoleMessage	messages	Captured console messages
Count	int	count	Number of messages

WebviewConsoleMessage fields

Field	Type	JSON key	Description
Type	string	type	Message level: log, warn, error, etc.
Text	string	text	Message content
Timestamp	string	timestamp	RFC 3339 timestamp
URL	string	url	Source URL (if available)
Line	int	line	Source line number (if available)

Notes

Returns an error if not connected. Messages accumulate in a buffer; use clear=true to reset the buffer after reading to avoid receiving duplicate messages on subsequent calls.

---

webview_eval

Evaluate a JavaScript expression in the browser context.

Parameters

Field	Type	JSON key	Required	Description
Script	string	script	Yes	JavaScript expression or statement to evaluate

Response

Field	Type	JSON key	Description
Success	bool	success	Whether evaluation succeeded
Result	any	result	Return value of the expression (JSON-serialisable)
Error	string	error	Error message if evaluation failed

Notes

Returns an error if not connected or if script is empty. JavaScript errors are captured in the error field with success=false rather than being returned as tool-level errors. Logged at Security level.

---

webview_screenshot

Capture a screenshot of the current browser viewport.

Parameters

Field	Type	JSON key	Required	Description
Format	string	format	No	Image format: "png" or "jpeg"; default "png"

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the screenshot was captured
Data	string	data	Base64-encoded image data
Format	string	format	Format used

Notes

Returns an error if not connected. The data field is standard base64 (not URL-safe); decode with standard base64 to obtain the raw image bytes.

---

webview_wait

Wait for an element matching a CSS selector to appear in the DOM.

Parameters

Field	Type	JSON key	Required	Description
Selector	string	selector	Yes	CSS selector to wait for
Timeout	int	timeout	No	Maximum wait time in seconds

Response

Field	Type	JSON key	Description
Success	bool	success	Whether the element appeared within the timeout
Message	string	message	Status message including the matched selector

Notes

Returns an error if not connected or if selector is empty. If the element does not appear before the timeout, an error is returned. The default timeout is inherited from the connection timeout set during webview_connect.

---

IDE Chat

Five tools for interacting with agent chat sessions via the Laravel WebSocket bridge. These tools are provided by the ide.Subsystem and require a ws.Hub instance for real-time forwarding.

Implementation status: The Laravel backend integration is currently a stub. Tool calls emit bridge messages and return placeholder responses. Live data is delivered asynchronously via WebSocket subscriptions.

---

ide_chat_send

Send a message to an agent chat session.

Parameters

Field	Type	JSON key	Required	Description
SessionID	string	sessionId	Yes	Target session identifier
Message	string	message	Yes	Message content to send

Response

Field	Type	JSON key	Description
Sent	bool	sent	Whether the message was forwarded to the bridge
SessionID	string	sessionId	Echoed session ID
Timestamp	time.Time	timestamp	Server-assigned send timestamp

Notes

The bridge forwards the message on the chat:<sessionId> channel. The agent's reply arrives asynchronously via the WebSocket connection. Returns an error if the bridge is not available.

---

ide_chat_history

Retrieve message history for a chat session.

Parameters

Field	Type	JSON key	Required	Description
SessionID	string	sessionId	Yes	Session identifier
Limit	int	limit	No	Maximum number of messages to return

Response

Field	Type	JSON key	Description
SessionID	string	sessionId	Echoed session ID
Messages	[]ChatMessage	messages	Message list (currently empty; data arrives via WebSocket)

ChatMessage fields

Field	Type	JSON key	Description
Role	string	role	"user" or "assistant"
Content	string	content	Message text
Timestamp	time.Time	timestamp	Message timestamp

Notes

Currently returns an empty messages array. The history request is forwarded to the Laravel backend via the bridge; data is returned asynchronously.

---

ide_session_list

List active agent sessions.

Parameters

None.

Response

Field	Type	JSON key	Description
Sessions	[]Session	sessions	Active sessions (currently empty; data arrives via WebSocket)

Session fields

Field	Type	JSON key	Description
ID	string	id	Session identifier
Name	string	name	Human-readable session name
Status	string	status	Session status string
CreatedAt	time.Time	createdAt	Session creation time

---

ide_session_create

Create a new agent session.

Parameters

Field	Type	JSON key	Required	Description
Name	string	name	Yes	Human-readable name for the new session

Response

Field	Type	JSON key	Description
Session	Session	session	The new session record

Notes

Currently returns a placeholder session with status="creating" and no id. The actual session is created asynchronously by the Laravel backend; the final record arrives via WebSocket.

---

ide_plan_status

Get the current plan status for an agent session.

Parameters

Field	Type	JSON key	Required	Description
SessionID	string	sessionId	Yes	Session identifier

Response

Field	Type	JSON key	Description
SessionID	string	sessionId	Echoed session ID
Status	string	status	Plan status; currently "unknown"
Steps	[]PlanStep	steps	Plan steps (currently empty)

PlanStep fields

Field	Type	JSON key	Description
Name	string	name	Step name
Status	string	status	Step status

---

IDE Build

Three tools for querying CI build status and logs. Provided by ide.Subsystem; data is sourced from the Laravel backend via the WebSocket bridge.

Implementation status: Stub. Tool calls emit bridge messages and return placeholder responses.

---

ide_build_status

Get the status of a specific build.

Parameters

Field	Type	JSON key	Required	Description
BuildID	string	buildId	Yes	Build identifier

Response

Field	Type	JSON key	Description
Build	BuildInfo	build	Build record

BuildInfo fields

Field	Type	JSON key	Description
ID	string	id	Build identifier
Repo	string	repo	Repository name
Branch	string	branch	Git branch
Status	string	status	Build status; currently "unknown"
Duration	string	duration	Build duration (if complete)
StartedAt	time.Time	startedAt	Build start time

---

ide_build_list

List recent builds, optionally filtered by repository.

Parameters

Field	Type	JSON key	Required	Description
Repo	string	repo	No	Filter by repository name
Limit	int	limit	No	Maximum number of builds to return

Response

Field	Type	JSON key	Description
Builds	[]BuildInfo	builds	Build records (currently empty)

---

ide_build_logs

Retrieve log output for a build.

Parameters

Field	Type	JSON key	Required	Description
BuildID	string	buildId	Yes	Build identifier
Tail	int	tail	No	Return only the last N lines

Response

Field	Type	JSON key	Description
BuildID	string	buildId	Echoed build identifier
Lines	[]string	lines	Log lines (currently empty)

---

IDE Dashboard

Three tools for querying platform-wide overview, activity, and aggregate metrics. Provided by ide.Subsystem; data is sourced from the Laravel backend via the WebSocket bridge.

Implementation status: ide_dashboard_overview returns live bridge connectivity status. The other two tools are stubs that forward requests and return placeholder responses.

---

ide_dashboard_overview

Get a high-level overview of the platform.

Parameters

None.

Response

Field	Type	JSON key	Description
Overview	DashboardOverview	overview	Platform summary

DashboardOverview fields

Field	Type	JSON key	Description
Repos	int	repos	Number of repositories (stub; currently 0)
Services	int	services	Number of services (stub; currently 0)
ActiveSessions	int	activeSessions	Active agent sessions (stub; currently 0)
RecentBuilds	int	recentBuilds	Recent build count (stub; currently 0)
BridgeOnline	bool	bridgeOnline	Whether the Laravel WebSocket bridge is currently connected

Notes

BridgeOnline is the only live field. All other fields return 0 until the Laravel backend integration is complete.

---

ide_dashboard_activity

Get the recent activity feed.

Parameters

Field	Type	JSON key	Required	Description
Limit	int	limit	No	Maximum number of events to return

Response

Field	Type	JSON key	Description
Events	[]ActivityEvent	events	Activity events (currently empty)

ActivityEvent fields

Field	Type	JSON key	Description
Type	string	type	Event category
Message	string	message	Human-readable description
Timestamp	time.Time	timestamp	Event timestamp

---

ide_dashboard_metrics

Get aggregate build and agent metrics for a time period.

Parameters

Field	Type	JSON key	Required	Description
Period	string	period	No	Time period: "1h", "24h", or "7d"; default "24h"

Response

Field	Type	JSON key	Description
Period	string	period	Echoed period
Metrics	DashboardMetrics	metrics	Aggregate metrics

DashboardMetrics fields

Field	Type	JSON key	Description
BuildsTotal	int	buildsTotal	Total builds in period
BuildsSuccess	int	buildsSuccess	Successful builds
BuildsFailed	int	buildsFailed	Failed builds
AvgBuildTime	string	avgBuildTime	Average build duration
AgentSessions	int	agentSessions	Agent sessions created
MessagesTotal	int	messagesTotal	Total chat messages
SuccessRate	float64	successRate	Build success ratio (0.0–1.0)

Notes

All fields currently return zero values. Data will be populated once the Laravel backend integration is complete.