# agents-io/pokeclaw architecture

> Architecture diagram of the GitHub repository agents-io/pokeclaw, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-17). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/agents-io/pokeclaw
- Repository: https://github.com/agents-io/pokeclaw

## Overview

#### Purpose and Runtime
PokeClaw is a phone-resident Android 9+ AI automation harness: it accepts chat/task requests, lets local LiteRT-LM models or optional cloud LLMs choose actions, and controls device/apps through Android services. It is not an ADB/host-driven framework. The app module is built with Gradle at `app/build.gradle.kts`; Android components and permissions are declared in `app/src/main/AndroidManifest.xml`.

#### Entry Points and Lifecycle
The application bootstrap is `app/src/main/java/io/agents/pokeclaw/ClawApplication.kt`. User-facing startup and chat/task interaction are centered on `app/src/main/java/io/agents/pokeclaw/ui/splash/SplashActivity.kt` and `app/src/main/java/io/agents/pokeclaw/ui/chat/ComposeChatActivity.kt`. Long-lived execution relies on foreground, boot-recovery, accessibility, and notification-listener components:
- `app/src/main/java/io/agents/pokeclaw/service/ForegroundService.kt`
- `app/src/main/java/io/agents/pokeclaw/service/ClawAccessibilityService.java`
- `app/src/main/java/io/agents/pokeclaw/service/ClawNotificationListener.java`

#### Task Orchestration and State
`app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt` coordinates task execution; `AppViewModel` exposes state to UI, and `TaskSessionStore` maintains task/session lifecycle. Chat-specific controllers and durable conversation history sit behind `app/src/main/java/io/agents/pokeclaw/ui/chat/ChatSessionController.kt`, `ConversationStore.kt`, and `ChatDatabase.kt`. The primary flow is: input or inbound trigger → task/chat controller → orchestrator → routing/execution → task events/results returned to the active conversation/channel.

#### Agent Routing, Safety, and Prompt Structure
The agent layer distinguishes deterministic/direct tasks, predefined skills, and full LLM-agent loops. `app/src/main/java/io/agents/pokeclaw/agent/PipelineRouter.kt` and `TaskClassifier.kt` select the path; `TaskParser.kt` normalizes intent. Prompt construction and reusable guidance are represented by `TaskPromptEnvelope.kt`, `PromptUtils.kt`, and asset playbooks such as `app/src/main/assets/playbooks/open-and-navigate.md`. Guards constrain risky or misleading behaviors, including `DirectDeviceDataGuard.kt`, `EmailComposeGuard.kt`, and `InAppSearchGuard.kt`. Budget, token, and loop-failure controls are in `TaskBudget.kt`, `TokenMonitor.kt`, and `StuckDetector.kt`.

#### LLM Boundary: Local and Cloud
`app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt` is the common agent service behind the selected model. `LlmClientFactory.kt` selects cloud or local clients. Cloud adapters include `OpenAiLlmClient.kt` and `AnthropicLlmClient.kt`; provider configuration is represented by `CloudProvider.kt`. Local inference is isolated in `app/src/main/java/io/agents/pokeclaw/agent/llm/LocalLlmClient.kt`, `LocalModelRuntime.kt`, and `LocalModelManager.kt`, using LiteRT-LM and model files managed on-device. This boundary allows identical tools and task harness behavior regardless of inference location.

#### Device-Action Boundary
LLMs do not manipulate Android directly: they invoke registered tools. `app/src/main/java/io/agents/pokeclaw/tool/ToolRegistry.kt` and `BaseTool.kt` define this execution boundary. Tools obtain screen/accessibility state or execute actions, e.g. `GetScreenInfoTool.java`, `InputTextTool.java`, and `OpenAppTool.java`; mobile gestures reside in `tool/impl/mobile/`. Accessibility service capabilities are therefore the critical boundary for observing UI trees and issuing device gestures. Skills compose generic tools through `app/src/main/java/io/agents/pokeclaw/agent/skill/SkillExecutor.kt` and `BuiltInSkills.kt`.

#### Inbound Automation, Channels, and External Services
External automation is an opt-in Android intent interface, exposed through `app/src/main/java/io/agents/pokeclaw/automation/ExternalAutomationActivity.kt`, `ExternalAutomationReceiver.kt`, and `ExternalAutomationContract.kt`; it feeds the normal task harness rather than bypassing safeguards. Messaging channels are mediated by `ChannelManager.kt`, with Discord, Telegram, and WeChat adapters under `channel/`. External dependencies include OpenAI/Anthropic-compatible cloud APIs, LiteRT-LM local runtime/model downloads, Android Accessibility and Notification Access, and GitHub Releases for updates. A localhost-oriented configuration server is implemented by `app/src/main/java/io/agents/pokeclaw/server/ConfigServer.kt`.

Main entry points: [`app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt`](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt) (Task orchestrator), [`app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt`](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt) (Common agent service), [`app/src/main/AndroidManifest.xml`](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/AndroidManifest.xml) (Component declarations), [`app/src/main/java/io/agents/pokeclaw/ClawApplication.kt`](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ClawApplication.kt) (Application bootstrap)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_android["Android lifecycle"]
  node_build["Gradle app module<br/>build<br/>[build.gradle.kts]"]
  node_manifest["Component declarations<br/>manifest"]
  node_application["Application bootstrap<br/>[ClawApplication.kt]"]
  node_ui["Splash and chat UI<br/>Android activities"]
  node_foreground["Foreground execution<br/>Android service"]
end

subgraph group_agent["Task intelligence"]
  node_orchestrator["Task orchestrator<br/>task coordinator"]
  node_sessions[("Chat and task state<br/>session persistence")]
  node_router["Pipeline router<br/>agent routing<br/>[PipelineRouter.kt]"]
  node_prompts["Prompts and playbooks<br/>agent guidance"]
  node_guards["Safety and loop controls<br/>agent guardrails"]
  node_agentservice["Common agent service<br/>LLM harness"]
  node_llmfactory["LLM client selection<br/>LLM factory"]
end

subgraph group_execution["Execution and integrations"]
  node_accessibility["Accessibility control<br/>Android accessibility service"]
  node_notifications["Notification listener<br/>Android listener"]
  node_local["Local LiteRT-LM<br/>on-device inference<br/>[LocalLlmClient.kt]"]
  node_cloud["Cloud LLM providers<br/>remote inference"]
  node_skills["Built-in skills<br/>tool composition<br/>[SkillExecutor.kt]"]
  node_tools["Tool registry<br/>device action boundary<br/>[ToolRegistry.kt]"]
  node_automation["External automation intents<br/>inbound Android interface"]
  node_channels["Messaging channels<br/>channel manager<br/>[ChannelManager.kt]"]
  node_configserver["Local config server<br/>localhost server<br/>[ConfigServer.kt]"]
end

node_build -->|"packages"| node_manifest
node_manifest -->|"launches"| node_application
node_application -->|"initializes"| node_ui
node_application -->|"runs"| node_foreground
node_manifest -->|"declares"| node_accessibility
node_manifest -->|"declares"| node_notifications
node_ui -->|"reads and writes"| node_sessions
node_ui -->|"submits tasks"| node_orchestrator
node_automation -->|"submits triggers"| node_orchestrator
node_channels -->|"forwards requests"| node_orchestrator
node_orchestrator -->|"publishes events"| node_sessions
node_orchestrator -->|"routes"| node_router
node_router -->|"selects skill path"| node_skills
node_router -->|"selects agent path"| node_agentservice
node_prompts -->|"guides"| node_agentservice
node_guards -->|"constrains"| node_agentservice
node_agentservice -->|"requests inference"| node_llmfactory
node_llmfactory -->|"selects"| node_local
node_llmfactory -->|"selects"| node_cloud
node_agentservice -->|"invokes tools"| node_tools
node_skills -->|"composes"| node_tools
node_tools -->|"observes and acts"| node_accessibility
node_notifications -->|"inbound events"| node_orchestrator
node_configserver -.->|"configures"| node_application

click node_build "https://github.com/agents-io/pokeclaw/blob/main/app/build.gradle.kts"
click node_manifest "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/AndroidManifest.xml"
click node_application "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ClawApplication.kt"
click node_ui "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ui/chat/ComposeChatActivity.kt"
click node_foreground "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/service/ForegroundService.kt"
click node_accessibility "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/service/ClawAccessibilityService.java"
click node_notifications "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/service/ClawNotificationListener.java"
click node_orchestrator "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt"
click node_sessions "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ui/chat/ChatSessionController.kt"
click node_router "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/PipelineRouter.kt"
click node_prompts "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/assets/playbooks/open-and-navigate.md"
click node_guards "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/DirectDeviceDataGuard.kt"
click node_agentservice "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt"
click node_local "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/llm/LocalLlmClient.kt"
click node_skills "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/skill/SkillExecutor.kt"
click node_tools "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/tool/ToolRegistry.kt"
click node_automation "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/automation/ExternalAutomationActivity.kt"
click node_channels "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/channel/ChannelManager.kt"
click node_configserver "https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/server/ConfigServer.kt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_build,node_manifest,node_application,node_ui,node_foreground toneBlue
class node_orchestrator,node_sessions,node_router,node_prompts,node_guards,node_agentservice,node_llmfactory toneAmber
class node_accessibility,node_notifications,node_local,node_cloud,node_skills,node_tools,node_automation,node_channels,node_configserver toneMint
```

## Components

### Android lifecycle

- [Gradle app module](https://github.com/agents-io/pokeclaw/blob/main/app/build.gradle.kts): build · `app/build.gradle.kts`
- [Component declarations](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/AndroidManifest.xml): manifest · Declares Android components and required permissions. · `app/src/main/AndroidManifest.xml`
- [Application bootstrap](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ClawApplication.kt): application · `app/src/main/java/io/agents/pokeclaw/ClawApplication.kt`
- [Splash and chat UI](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ui/chat/ComposeChatActivity.kt): Android activities · `app/src/main/java/io/agents/pokeclaw/ui/chat/ComposeChatActivity.kt`
- [Foreground execution](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/service/ForegroundService.kt): Android service · `app/src/main/java/io/agents/pokeclaw/service/ForegroundService.kt`

### Task intelligence

- [Task orchestrator](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt): task coordinator · `app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt`
- [Chat and task state](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/ui/chat/ChatSessionController.kt): session persistence · Maintains task lifecycle and durable conversation history. · `app/src/main/java/io/agents/pokeclaw/ui/chat/ChatSessionController.kt`
- [Pipeline router](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/PipelineRouter.kt): agent routing · Selects direct, skill, or LLM-agent execution. · `app/src/main/java/io/agents/pokeclaw/agent/PipelineRouter.kt`
- [Prompts and playbooks](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/assets/playbooks/open-and-navigate.md): agent guidance · `app/src/main/assets/playbooks/open-and-navigate.md`
- [Safety and loop controls](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/DirectDeviceDataGuard.kt): agent guardrails · Constrains risky actions and budget or stuck loops. · `app/src/main/java/io/agents/pokeclaw/agent/DirectDeviceDataGuard.kt`
- [Common agent service](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt): LLM harness · `app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt`
- **LLM client selection**: LLM factory

### Execution and integrations

- [Accessibility control](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/service/ClawAccessibilityService.java): Android accessibility service · Observes UI trees and issues device gestures. · `app/src/main/java/io/agents/pokeclaw/service/ClawAccessibilityService.java`
- [Notification listener](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/service/ClawNotificationListener.java): Android listener · `app/src/main/java/io/agents/pokeclaw/service/ClawNotificationListener.java`
- [Local LiteRT-LM](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/llm/LocalLlmClient.kt): on-device inference · Uses managed on-device model files and runtime. · `app/src/main/java/io/agents/pokeclaw/agent/llm/LocalLlmClient.kt`
- **Cloud LLM providers**: remote inference · OpenAI- and Anthropic-compatible adapters.
- [Built-in skills](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/agent/skill/SkillExecutor.kt): tool composition · `app/src/main/java/io/agents/pokeclaw/agent/skill/SkillExecutor.kt`
- [Tool registry](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/tool/ToolRegistry.kt): device action boundary · Registered tools are the only LLM path to device actions. · `app/src/main/java/io/agents/pokeclaw/tool/ToolRegistry.kt`
- [External automation intents](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/automation/ExternalAutomationActivity.kt): inbound Android interface · Opt-in triggers enter the normal task harness. · `app/src/main/java/io/agents/pokeclaw/automation/ExternalAutomationActivity.kt`
- [Messaging channels](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/channel/ChannelManager.kt): channel manager · Mediates Discord, Telegram, and WeChat adapters. · `app/src/main/java/io/agents/pokeclaw/channel/ChannelManager.kt`
- [Local config server](https://github.com/agents-io/pokeclaw/blob/main/app/src/main/java/io/agents/pokeclaw/server/ConfigServer.kt): localhost server · `app/src/main/java/io/agents/pokeclaw/server/ConfigServer.kt`

## Connections

- Gradle app module → Component declarations: packages
- Component declarations → Application bootstrap: launches
- Application bootstrap → Splash and chat UI: initializes
- Application bootstrap → Foreground execution: runs
- Component declarations → Accessibility control: declares
- Component declarations → Notification listener: declares
- Splash and chat UI → Chat and task state: reads and writes
- Splash and chat UI → Task orchestrator: submits tasks
- External automation intents → Task orchestrator: submits triggers
- Messaging channels → Task orchestrator: forwards requests
- Task orchestrator → Chat and task state: publishes events
- Task orchestrator → Pipeline router: routes
- Pipeline router → Built-in skills: selects skill path
- Pipeline router → Common agent service: selects agent path
- Prompts and playbooks → Common agent service: guides
- Safety and loop controls → Common agent service: constrains
- Common agent service → LLM client selection: requests inference
- LLM client selection → Local LiteRT-LM: selects
- LLM client selection → Cloud LLM providers: selects
- Common agent service → Tool registry: invokes tools
- Built-in skills → Tool registry: composes
- Tool registry → Accessibility control: observes and acts
- Notification listener → Task orchestrator: inbound events
- Local config server → Application bootstrap: configures