PiClaw - Agent de Codificação IA
cotapelu/qclaw
Agent IA para desenvolvimento com git, testes e segurança integrados
Ver no GitHubAgent terminal profissional para desenvolvimento assistido por IA, construído sobre pi-sdk com ecossistema de 23+ extensões. Integra ferramentas como git, testes, formatação, auditoria e scanner de segurança, oferecendo interface interativa com comandos slash, widgets ao vivo e arquitetura modular.
Instalação
npx convez-ai cotapelu/qclaw1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Assistência em codificação com contexto de projeto
- Automação de operações git, testes e build
- Refatoração e review de código com IA
- Detecção de vazamento de secrets e auditoria
Veredito

Agent robusto e bem arquitetado para desenvolvimento full-cycle com foco em segurança. Excelente para equipes que querem automação de tarefas repetitivas, mas requer familiaridade com terminal e configuração inicial.
README
A tradução para o português deste README ainda está na fila.
PiClaw
PiClaw is a professional AI coding agent built on pi-coding-agent. It provides a powerful terminal-based interface for AI-assisted development.
Features
- Rich Extension Ecosystem: 23+ extensions including tools, commands, renderers, and widgets.
- Integrated Tools:
git(full git operations),test(vitest runner),formatter(Prettier),audit(npm audit),build(npm run build),metrics(export stats),memory(persistent memories),todos(project todo management),scripts(npm scripts),secret-scanner(detect leaked keys). - Interactive Slash Commands:
/tree(session browser),/settings(config UI),/providers(LLM provider management),/copy(clipboard),/team(toggle team widget),/scan-secrets(security scan),/scripts(run npm scripts). - Custom Renderers: Beautiful output for branch summaries, team ops, compaction summaries.
- Session Widgets: Live team status widget with toggle.
- Secure by Default: SDK factories, validated inputs, no eval; file writes use mutation queue.
- Prompt Templates: Built-in defaults (
default,explain,refactor,test,review). - Highly Configurable:
~/.piclaw/config.jsonor CLI flags; thinking level and model persistence. - Modular Architecture: Easy to add new extensions; all registered via
factory.ts.
Extension System
PiClaw loads extensions from src/extensions/ automatically. Extensions can register:
- Tools: Callable by the LLM (e.g.,
git,test,formatter). - Commands: Slash commands invoked by the user (e.g.,
/tree,/team). - Renderers: Custom UI for tool results and session entries.
- Widgets: TUI components that display live information.
All extensions follow the SDK patterns for consistency and safety.
Security Model
- No arbitrary
evalor unsanitized command execution. - Tools that run shell commands use
createBashToolwith safe defaults. - File mutation operations use
withFileMutationQueueto prevent race conditions. - Secret scanner helps detect accidental key leaks.
For more details, see docs/AGENT_PROFILE.md.
Installation
# Clone and install
npm install
npm run build
npm link
Usage
Start the interactive agent:
piclaw
Or with options:
piclaw --cwd /path/to/project --model anthropic:claude-opus-4-5 --thinking high --verbose
CLI Options
--cwd <path>- Working directory (default: current)--tools <list>- Comma-separated tool allowlist (overrides config)--sessionDir <dir>- Custom session storage directory--model <id>- Model to use (e.g.,anthropic:claude-opus-4-5)--thinking <level>- Thinking level:off|minimal|low|medium|high|xhigh--verbose- Show detailed logs
Configuration
Piclaw stores configuration in ~/.piclaw/config.json. Example:
{
"model": "anthropic:claude-opus-4-5",
"thinking": "high",
"tools": ["read", "bash", "edit", "write", "grep", "find"],
"verbose": false
}
You can edit this file manually or use the /piclaw-set command inside the agent.
Supported Config Keys
model- Default model (provider:modelId)thinking- Default thinking leveltools- Array of allowed tool namessessionDir- Custom session storage pathverbose- Enable verbose logging
Slash Commands
PiClaw adds several powerful slash commands to the standard pi set.
Configuration
/settings– Open interactive settings panel/config– Display current Piclaw configuration/piclaw-set <key> <value>– Set a configuration value (e.g.,/piclaw-set model anthropic:claude-opus-4-5)/tools– List the currently allowed tools/piclaw-status– Show Piclaw and session status
Navigation & Inspection
/tree– Interactive session tree browser with entry details/session– Show session information
Provider & Model Management
/providers– Manage LLM providers (list,add <name> <baseUrl> <apiKey>,remove <name>,test <name>)
Workspace Utilities
/copy– Copy the last assistant response to clipboard/scan-secrets– Scan the workspace for leaked API keys and tokens/scripts– List and run npm scripts (/scriptsto list,scripts({ action: 'run', script: 'name' }))
Team & Collaboration
/team– Toggle the team status widget visibility
Standard pi Commands
/model– Select model (opens UI)/thinking– Change thinking level/quit– Exit- ... and many more. Press
/in the app to see all commands.
Development
# Build
npm run build
# Run in dev mode (tsx)
npm run dev
# Lint
npm run lint
# Type check
npm run check
# Test
npm test
How It Works
Piclaw extends pi-coding-agent with:
- Config Manager - Loads/saves user configuration
- CLI Resolution - Merges CLI options with config file
- Tool Allowlist - Applies
toolsconfig to session - Auto-Loaded Extension - Registers custom slash commands via global settings
On startup, Piclaw:
- Loads config from
~/.piclaw/config.json - Merges with CLI overrides
- Registers the built-in piclaw extension (written in
src/extensions/piclaw-extension.ts) - Creates agent session with allowed tools from config
- Applies initial model and thinking level
Extension Architecture
Piclaw's custom extension is automatically registered by writing its path to the global settings file (~/.piclaw/agent/settings.json). This happens on every startup (if not already present).
To create your own extension, place a .ts or .js file in:
- Global:
~/.pi/agent/extensions/ - Project:
<project>/.pi/extensions/
See examples in llm-context/packages/coding-agent/examples/extensions/.
License
APACHE
Team Collaboration
PiClaw supports multi-agent team collaboration. Spawn multiple agents to work together on tasks with automatic work distribution, messaging, and conflict resolution.
Key Features
- Dynamic task assignment with work stealing
- Message bus for agent-to-agent communication
- Shared workspace with optimistic locking & conflict resolution
- Team context for shared awareness of progress, blockers, decisions
- Auto-continue across team members
Usage
Use the spawn_team tool to create and manage teams:
spawn_team({ action: "create", tasks: ["Design API", "Implement backend", "Write tests"], size: 3 })
Child agents can use team_ops to coordinate:
team_ops({ action: "claim_task" }) // Get next available task
team_ops({ action: "workspace_write", key: "design", value: "{}" }) // Share data
team_ops({ action: "send_message", channel: "team.chat", content: "Done with task 1" })
Events emitted: team_created, team_progress, team_completed, team_disposed.
Custom Tools & Extensions
PiClaw includes several built-in custom tools extending the base pi-coding-agent:
- todos - Full-featured todo management with phases & tasks (persists to
.piclaw/agent/todos.json) - memory - Store and retrieve arbitrary text snippets with tags (persists in session)
- echo - Simple demonstration tool for custom tool registration
- system_info - Get system diagnostics (OS, memory, CPU, uptime)
- team / team_ops - Team collaboration tools
Additionally, custom provider support allows adding new LLM providers (e.g., Kilo Gateway).
Metrics & Observability
Team collaboration includes optional metrics collection to monitor performance and diagnose issues.
Enabled Metrics
- Task completion times & distribution
- Agent workload & efficiency
- Workspace conflicts & lock wait times
- Message traffic & channel usage
- Work stealing frequency & success rate
- Help requests & assistance provided
Accessing Metrics
// After team completion, get metrics summary
const summary = teamMetrics.getSummary();
console.log(summary);
// Export to JSON for analysis
await exportMetricsToFile(team, "./metrics.json");
Metrics are collected via src/team/team-metrics.ts and integrated via src/team/team-metrics-integration.ts. See CONTRIBUTING.md for integration details.