ttguy0707/CyberClaw

What it solves

CyberClaw is a general-purpose AI agent framework designed to make agentic workflows more observable, secure, and extensible. It addresses the problem of unreliable tool execution by introducing a strict "help $\rightarrow$ run" protocol for dynamic skills, ensuring the agent has accessed the latest instructions before executing a command.

How it works

Built on LangGraph, the project implements a state graph (START $\rightarrow$ agent $\rightarrow$ tools $\rightarrow$ agent). It uses an AsyncSqliteSaver for session persistence and a Markdown-based user profile for long-term memory. To manage context, it trims messages after 40 turns, keeping the latest 10 and summarizing the rest via an LLM.

Key technical mechanisms include:

• Two-Phase Skill Execution: Skills are not called directly; the agent must first request help to receive a one-time help_token. This token must be provided during the run phase, and is validated against the session, skill identity, and content hash before execution.
• Subagent Delegation: The main agent can delegate tasks to specialized sub-agents (like a code_reviewer or document_analyst) or define temporary roles on the fly. These sub-agents operate in isolated contexts with restricted tool access.
• Scheduled Tasks: A heartbeat coroutine checks a tasks.json file every 10 seconds to trigger timed actions.
• Observability: A bounded asynchronous queue logs five types of events (LLM input, tool calls, results, AI messages, and system actions) into JSONL files, viewable via a dedicated monitor CLI.

Who it’s for

• Developers building autonomous agents who need a structured way to manage dynamic tools and skills.
• Users who want a CLI-based AI assistant with long-term memory and the ability to delegate complex tasks to specialized sub-agents.
• Those looking for a framework that enforces a protocol-based approach to tool calling to increase reliability.

Highlights

• Enforced Protocol: Prevents arbitrary tool execution by requiring a valid, time-limited token from a help call.
• Hierarchical Agency: Supports both preset and dynamically defined sub-agents with isolated contexts.
• Context Management: Automatic LLM-based summarization and turn-based trimming to handle long conversations.
• Built-in Toolset: Includes 13 core tools for file system operations, shell execution (with allowlists), scheduling, and profile management.
• Structured Auditing: Real-time monitoring of agent decision-making and tool interactions via JSONL logs.