Skip to main content

​
Overview

Session tools enable multi-agent orchestration. One agent can spawn a child session, send it a task, and check back on its progress - enabling parallel workstreams and specialized sub-agents. profClaw has two sets of session tools:
  • Sessions tools (sessions_*) - manage conversation sessions as persistent chat threads
  • Session spawn tools (spawn_session, send_message, etc.) - hierarchical agent-to-agent communication

​
Sessions Tools

​
sessions_spawn

Spawn a new chat session with an optional initial task. Security level: moderate | Tier: Full
​
title
string
Title for the new session. Auto-generated from the task if not provided.
​
task
string
Initial task or message to send to the new session.
​
presetId
string
default:"profclaw-assistant"
Skill preset for the session: profclaw-assistant, code-assistant, git-workflow, etc.
​
projectId
string
Link this session to a project.
​
ticketId
string
Link this session to a specific ticket for focused work.
​
mode
string
default:"chat"
Session mode: chat (conversational) or agentic (autonomous execution).
​
metadata
object
Additional key-value metadata to attach to the session.
{
  "title": "Refactor auth module",
  "task": "Analyze src/auth/ and suggest a refactoring plan to split it into smaller modules",
  "presetId": "code-assistant",
  "mode": "agentic",
  "ticketId": "PC-88"
}

​
sessions_list

List active or recent sessions. Security level: safe | Tier: Full
​
status
string
Filter by status: active, idle, completed.
​
projectId
string
Filter by project.
​
limit
number
default:"20"
Maximum sessions to return.

​
sessions_send

Send a message to an existing session. Security level: moderate | Tier: Full
​
sessionId
string
required
Target session ID.
​
message
string
required
Message to send.

​
session_status

Get the current status and model of an active session. Security level: safe | Tier: Full
​
sessionId
string
Session ID. Defaults to the current session.

​
Hierarchical Agent Tools

These tools are used by an orchestrator agent to spawn and coordinate worker agents.

​
spawn_session

Spawn a dedicated worker agent session.
​
name
string
required
Name for the worker session.
​
instructions
string
required
System-level instructions for the worker.
​
model
string
Override the AI model for this worker (useful for routing cheap tasks to smaller models).

​
send_message

Send a message to a spawned worker and await a response.
​
sessionId
string
required
Worker session ID returned by spawn_session.
​
message
string
required
Task or message to send.
​
timeout
number
default:"300000"
Maximum time to wait for a response in milliseconds.

​
receive_messages

Poll for new messages from a worker session without blocking.

​
list_sessions

List all spawned worker sessions from the current conversation.

​
Multi-Agent Patterns

Spawn multiple agents to research different topics simultaneously, then synthesize:
1. spawn_session("researcher-1") - "Research Hono middleware patterns"
2. spawn_session("researcher-2") - "Research BullMQ queue patterns"
3. send_message("researcher-1", "find best practices")
4. send_message("researcher-2", "find best practices")
5. receive_messages from both
6. Synthesize results

profClaw Ops

Link sessions to tickets for focused work.

Memory

Share knowledge across sessions via memory files.