convez.ai
AgenteAutomaçãoIntermediário
is0383kk

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 GitHub
InicialPluginScore · de 0 a 100

Sistema 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-assistant

1 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

Estrelas
5
Forks
1
Acompanhando
0
Saúde
42%
Último commit
há 6 meses
Versão
—
Issues abertas
0
Contribuidores
1

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

FeatureCommand / Endpoint
Daemon start / stop / restart / statuscasra start/stop/restart/status
Send message (streaming)casra -m "message"
stdin / pipe inputecho "question" | casra
View logscasra logs [--tail N]
Session managementcasra sessions
Cron job managementcasra cron add/list/delete/run/edit
HTTP REST APIPOST /message, POST /message/stream, GET /status, etc.
Cron REST APIGET /cron, POST /cron, PATCH /cron/{id}, DELETE /cron/{id}, etc.
Discord integrationAuto-connect on daemon start (configure via casra config set)
Slack integrationAuto-connect on daemon start (configure via casra config set)
HeartbeatPeriodic polling via casra config set heartbeat.every 30m

Setup

Prerequisites

Dependencies

PackagePurpose
claude-agent-sdk>=0.1.48Claude AI Agent SDK
fastapi>=0.115.0REST API framework
uvicorn>=0.30.0ASGI server
apscheduler>=3.10,<4Cron job scheduler (v3.x)
discord.py>=2.3Discord Bot (optional)
slack-bolt>=1.18Slack 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/. Since src/config.py uses Path.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.md does 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:

  1. Create an application in the Discord Developer Portal and obtain a Bot Token
  2. Enable Message Content Intent in the Bot settings
  3. 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_id is not set, the Bot will not start (a warning is logged). Alternatively, set the token via the environment variable DISCORD_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:

  1. Create an application in the Slack API Portal and install it to your workspace
  2. Enable Socket Mode and obtain an App-Level Token (xapp- prefix) with the connections:write scope
  3. Add the following Bot Token Scopes: chat:write, reactions:write, channels:history, im:history, app_mentions:read
  4. Enable the Event Subscriptions and subscribe to message.im and app_mention bot events
  5. 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_token and slack.app_token must be set for the Bot to start. Tokens can also be set via environment variables SLACK_BOT_TOKEN and SLACK_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.

MethodPathDescription
POST/messageSend message (full response)
POST/message/streamSend message (SSE streaming)
GET/statusDaemon status and PID
GET/sessionsList sessions
DELETE/sessionsDelete all sessions
DELETE/sessions/{id}Delete a specific session
GET/cronList cron jobs
POST/cronAdd a cron job
PATCH/cron/{id}Edit a cron job
DELETE/cron/{id}Delete a cron job
POST/cron/{id}/runRun a cron job manually
Ver o original no GitHub

Bom para

Relacionados