Casra — Assistente de IA Pessoal Nativo com Claude
is0383kk/claude-agent-sdk-resident-assistant
Assistente de IA persistente com CLI, API REST e integrações sociais
Ver no GitHubSistema de agente de IA persistente construído com claude-agent-sdk que funciona como assistente pessoal operando a partir de configurações locais. Oferece interface CLI, REST API e integração com Discord/Slack, gerenciamento de sessões e agendamento de tarefas cron.
Instalação
npx convez-ai is0383kk/claude-agent-sdk-resident-assistant1 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
- Automação de tarefas repetitivas via CLI ou REST API
- Assistente pessoal com contexto persistente entre sessões
- Integração com Discord e Slack para interações automatizadas
- Agendamento de jobs recorrentes com cron
Veredito

Solução robusta e completa para automação pessoal ou empresarial com Claude. Requer instalação local e configuração inicial, mas oferece flexibilidade real via CLI, API e integrações maduras com plataformas sociais.
README
A tradução para o português deste README ainda está na fila.
🦀Casra — Claude Code-native personal AI assistant
A persistent AI agent system built with claude-agent-sdk. Operates based on Claude Code's settings.json.
This project is inspired by OpenClaw.
Runs as a Unix socket server, accepting messages from the CLI and REST API and proxying them to Claude.
Features
| Feature | Command / Endpoint |
|---|---|
| Daemon start / stop / restart / status | casra start/stop/restart/status |
| Send message (streaming) | casra -m "message" |
| stdin / pipe input | echo "question" | casra |
| View logs | casra logs [--tail N] |
| Session management | casra sessions |
| Cron job management | casra cron add/list/delete/run/edit |
| HTTP REST API | POST /message, POST /message/stream, GET /status, etc. |
| Cron REST API | GET /cron, POST /cron, PATCH /cron/{id}, DELETE /cron/{id}, etc. |
| Discord integration | Auto-connect on daemon start (configure via casra config set) |
| Slack integration | Auto-connect on daemon start (configure via casra config set) |
| Heartbeat | Periodic polling via casra config set heartbeat.every 30m |
Setup
Prerequisites
- Linux / Windows (WSL2)
- Python >= 3.14
- An environment where claude-agent-sdk is available
Dependencies
| Package | Purpose |
|---|---|
claude-agent-sdk>=0.1.48 | Claude AI Agent SDK |
fastapi>=0.115.0 | REST API framework |
uvicorn>=0.30.0 | ASGI server |
apscheduler>=3.10,<4 | Cron job scheduler (v3.x) |
discord.py>=2.3 | Discord Bot (optional) |
slack-bolt>=1.18 | Slack Bot (optional) |
Installation
git clone <repository-url> ~/.casra
cd ~/.casra
pip install -r requirements.txt
# Add to PATH (~/.bashrc)
echo '[ -d "$HOME/.casra" ] && export PATH="$HOME/.casra:$PATH"' >> ~/.bashrc
# Enable tab completion (~/.bashrc)
echo 'eval "$(register-python-argcomplete casra)"' >> ~/.bashrc
source ~/.bashrc
Note: The project must be placed in
~/.casra/. Sincesrc/config.pyusesPath.home() / ".casra"as the base path, it will not work in a different directory.
Usage
Daemon Management
# Start (default port: 28789)
casra start
# Start with a specific port
casra start --port 18789
# Stop
casra stop
# Restart
casra restart
# Check status
casra status
# View logs
casra logs # full output
casra logs --tail 50 # last 50 lines
Sending Messages
# Simple send
casra -m "prompt"
# Specify a session
casra --session-id work -m "prompt"
# stdin / pipe
echo "question" | casra
cat report.txt | casra -m "Summarize this"
git diff | casra -m "Review this diff"
Session Management
# List sessions
casra sessions
# Delete all sessions
casra sessions cleanup
# Delete a specific session
casra sessions delete <session-id>
Cron Jobs
# Add a job (runs every morning at 9:00)
casra cron add "0 9 * * *" --name "morning" --session main -m "Organize today's tasks"
# List jobs
casra cron list
# Run manually
casra cron run <job-id>
# Edit a job (patch any combination of fields)
casra cron edit <job-id> --name "new name"
casra cron edit <job-id> --schedule "0 10 * * *" --message "Updated prompt"
casra cron edit <job-id> --session work
casra cron edit <job-id> --disable
casra cron edit <job-id> --enable
# Delete a job
casra cron delete <job-id>
Heartbeat
Run periodic agent turns on the main session to process a checklist in ~/.casra/HEARTBEAT.md.
Unlike Cron, Heartbeat preserves the main session's conversation context across executions.
If the agent replies with only HEARTBEAT_OK, the response is suppressed (logged only).
Setup:
# Enable heartbeat (every 30 minutes)
casra config set heartbeat.every 30m
# Disable heartbeat
casra config set heartbeat.every 0m
# Temporarily pause without losing the interval setting
casra config set heartbeat.disabled true
# Set active hours (only runs between 09:00 and 22:00)
casra config set heartbeat.active_hours.start "09:00"
casra config set heartbeat.active_hours.end "22:00"
# Restart daemon to apply
casra restart
HEARTBEAT.md:
Create ~/.casra/HEARTBEAT.md with a checklist for the agent to process:
# Heartbeat Checklist
- Check for any urgent pending tasks
- If nothing needs attention, reply HEARTBEAT_OK
Note: If
HEARTBEAT.mddoes not exist, the daemon runs with the default prompt only. If the file contains only headings or blank lines, the execution is skipped to reduce API calls.
Verify:
Check that the following messages appear in the logs:
Heartbeat scheduler started (interval=1800s)
HEARTBEAT_OK (suppressed)
If the agent has something to report, the log shows Heartbeat alert (len=N) instead.
Discord Integration
Connect a Discord Bot to receive and reply to messages in a specified channel.
Prerequisites:
- Create an application in the Discord Developer Portal and obtain a Bot Token
- Enable Message Content Intent in the Bot settings
- Invite the Bot to your server via the OAuth2 URL
Setup:
# Set Bot Token (required)
casra config set discord.bot_token <YOUR_BOT_TOKEN>
# Set target channel ID (required — right-click channel → Copy Channel ID)
casra config set discord.channel_id <YOUR_CHANNEL_ID>
# Set session to use (optional, default: "discord")
casra config set discord.session_id discord2
# Restart daemon to apply
casra restart
Note: If
discord.channel_idis not set, the Bot will not start (a warning is logged). Alternatively, set the token via the environment variableDISCORD_BOT_TOKEN.
Verify:
Check that the following messages appear in the logs:
Discord bot starting (channel_id=..., session=...)
Discord bot ready (logged in as <BotName>)
Once running, any message sent to the configured channel will be forwarded to Claude and replied to by the Bot.
Slack Integration
Connect a Slack Bot to receive and reply to DMs and channel mentions via Socket Mode.
Prerequisites:
- Create an application in the Slack API Portal and install it to your workspace
- Enable Socket Mode and obtain an App-Level Token (
xapp-prefix) with theconnections:writescope - Add the following Bot Token Scopes:
chat:write,reactions:write,channels:history,im:history,app_mentions:read - Enable the Event Subscriptions and subscribe to
message.imandapp_mentionbot events - Obtain the Bot Token (
xoxb-prefix) from the Install App page
Setup:
# Set Bot Token (required, xoxb- prefix)
casra config set slack.bot_token <YOUR_BOT_TOKEN>
# Set App Token (required, xapp- prefix)
casra config set slack.app_token <YOUR_APP_TOKEN>
# Set session to use (optional, default: "slack")
casra config set slack.session_id slack2
# Restart daemon to apply
casra restart
Note: Both
slack.bot_tokenandslack.app_tokenmust be set for the Bot to start. Tokens can also be set via environment variablesSLACK_BOT_TOKENandSLACK_APP_TOKEN.
Advanced options:
# Restrict DMs to specific users (default: "open" — allow all)
casra config set slack.dm_policy allowlist
casra config set slack.allow_from '["U01234567", "U09876543"]'
# Restrict channel mentions to specific channels (default: "open" — allow all)
casra config set slack.channel_policy allowlist
casra config set slack.channels '["C01234567"]'
Verify:
Check that the following messages appear in the logs:
Slack bot starting (session=...)
Slack bot ready (logged in as <BotName>, team=<TeamName>)
Once running, DMs to the Bot and @mentions in channels will be forwarded to Claude and replied to by the Bot.
systemd Integration (if configured)
systemctl --user start casra
systemctl --user stop casra
systemctl --user status casra
REST API
After starting the daemon, it is accessible at http://localhost:28789 by default.
| Method | Path | Description |
|---|---|---|
POST | /message | Send message (full response) |
POST | /message/stream | Send message (SSE streaming) |
GET | /status | Daemon status and PID |
GET | /sessions | List sessions |
DELETE | /sessions | Delete all sessions |
DELETE | /sessions/{id} | Delete a specific session |
GET | /cron | List cron jobs |
POST | /cron | Add a cron job |
PATCH | /cron/{id} | Edit a cron job |
DELETE | /cron/{id} | Delete a cron job |
POST | /cron/{id}/run | Run a cron job manually |