Skip to main content
The agent module lives in packages/core/src/agent/.

​
runAgent

The entry point is runAgent, an async generator that yields typed events: 
import { runAgent } from "@grindxp/core/agent";

for await (const event of runAgent({ messages, settings, db })) {
  switch (event.type) {
    case "text-delta": // streaming text token
    case "tool-call": // tool invocation started
    case "tool-result": // tool result returned
    case "reasoning": // extended thinking step
    case "usage": // token usage summary
    case "error": // error occurred
    case "done": // stream complete
  }
}
The TUI’s ChatApp.tsx and the CLI’s chat command both consume this generator.

​
Tools

The agent has access to 18 tools defined in agent/tools.ts. Tools are divided by capability level:

​
Quest & Life OS Tools (always available)

ToolDescription
create_questCreate a new quest
complete_questComplete a quest
start_timerStart a timer on a quest
stop_timerStop the running timer
abandon_questAbandon a quest
list_questsList quests with filtering
get_statusGet character stats and overview
analyze_patternsAnalyze completion patterns and suggest improvements
suggest_questSuggest new quests based on goals

​
System Tools (require trust level ≥ 2)

ToolPermission Required
read_fileTrust ≥ 2
globTrust ≥ 2
grepTrust ≥ 2
fetch_urlTrust ≥ 2
web_searchTrust ≥ 2

​
Write Tools (require trust level ≥ 3, user approval at level 3)

ToolPermission Required
write_fileTrust ≥ 3
edit_fileTrust ≥ 3
bashTrust ≥ 3
At trust level 3 (Agent), write tools prompt the user for approval. At trust level 4 (Sovereign), no approval is needed.

​
Session Persistence

agent/sessions.ts handles conversation persistence:
  • Messages are stored in the messages table
  • Each conversation has a record in conversations
  • appendMessage adds each new message atomically
  • loadSession reconstructs the message history for a conversation
  • compactSession summarizes older messages when the context window fills

​
Context Compaction

agent/compaction.ts implements context window management:
  1. When token usage exceeds a threshold, compaction is triggered
  2. The oldest messages (excluding the system prompt) are summarized
  3. The summary replaces the compacted messages
  4. Conversation continues with the summary in context
Manual compaction is available via /compact in the TUI.

​
Extended Thinking

For Anthropic models, extended thinking (chain-of-thought) is supported: 
runAgent({
  ...,
  thinking: { type: 'enabled', budgetTokens: 8000 }
})
Thinking tokens are streamed as reasoning events and displayed separately in the TUI.

​
Adding a New Tool

  1. Define the tool in agent/tools.ts using Vercel AI SDK’s tool() helper
  2. Add a permission check if it requires elevated trust
  3. Add the tool to the tools object passed to generateText / streamText
  4. Add rendering logic in the TUI’s ChatApp.tsx for tool call display