How agents-io/pokeclaw works
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: TaskOrchestrator.kt Task orchestrator · DefaultAgentService.kt Common agent service · AndroidManifest.xml Component declarations · ClawApplication.kt Application bootstrap
Components 21
Android lifecycle
- Gradle app module
app/build.gradle.kts - Component declarations · Declares Android components and required permissions.
app/src/main/AndroidManifest.xml - Application bootstrap
app/src/main/java/io/agents/pokeclaw/ClawApplication.kt - Splash and chat UI
app/src/main/java/io/agents/pokeclaw/ui/chat/ComposeChatActivity.kt - Foreground execution
app/src/main/java/io/agents/pokeclaw/service/ForegroundService.kt
Task intelligence
- Task orchestrator
app/src/main/java/io/agents/pokeclaw/TaskOrchestrator.kt - Chat and task state · Maintains task lifecycle and durable conversation history.
app/src/main/java/io/agents/pokeclaw/ui/chat/ChatSessionController.kt - Pipeline router · Selects direct, skill, or LLM-agent execution.
app/src/main/java/io/agents/pokeclaw/agent/PipelineRouter.kt - Prompts and playbooks
app/src/main/assets/playbooks/open-and-navigate.md - Safety and loop controls · Constrains risky actions and budget or stuck loops.
app/src/main/java/io/agents/pokeclaw/agent/DirectDeviceDataGuard.kt - Common agent service
app/src/main/java/io/agents/pokeclaw/agent/DefaultAgentService.kt - LLM client selection
Execution and integrations
- Accessibility control · Observes UI trees and issues device gestures.
app/src/main/java/io/agents/pokeclaw/service/ClawAccessibilityService.java - Notification listener
app/src/main/java/io/agents/pokeclaw/service/ClawNotificationListener.java - Local LiteRT-LM · Uses managed on-device model files and runtime.
app/src/main/java/io/agents/pokeclaw/agent/llm/LocalLlmClient.kt - Cloud LLM providers · OpenAI- and Anthropic-compatible adapters.
- Built-in skills
app/src/main/java/io/agents/pokeclaw/agent/skill/SkillExecutor.kt - Tool registry · Registered tools are the only LLM path to device actions.
app/src/main/java/io/agents/pokeclaw/tool/ToolRegistry.kt - External automation intents · Opt-in triggers enter the normal task harness.
app/src/main/java/io/agents/pokeclaw/automation/ExternalAutomationActivity.kt - Messaging channels · Mediates Discord, Telegram, and WeChat adapters.
app/src/main/java/io/agents/pokeclaw/channel/ChannelManager.kt - Local config server
app/src/main/java/io/agents/pokeclaw/server/ConfigServer.kt
Connections 24
- 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