Claude Code Agent - Home Assistant Add-on

A Home Assistant add-on that runs Claude Code as an automated agent with c3po multi-agent coordination.

Overview

This add-on enables running Claude Code continuously inside Home Assistant, connected to a c3po coordinator for multi-agent collaboration. Unlike interactive Claude Code sessions, this focuses on agent mode - automated task execution, scheduled work, and coordination with other agents.

Features

Runs Claude Code as a long-lived service (not Docker-in-Docker)
Integrated with c3po for multi-agent coordination
Non-root execution (runs as UID 1000)
Read-write access to Home Assistant configuration
Persistent credential storage
S6 process supervision
Health checks and automatic restart on failure

Architecture

Simplified Design

The add-on is intentionally simple:

Base Image: Home Assistant add-on base (Alpine Linux with S6)
Runtime: Node.js with Claude Code installed globally
Service: Single S6 service that runs claude -p "/c3po auto"
Storage: Persistent /data volume for credentials and state

No Python orchestration, no subprocess management, no complexity. The c3po plugin handles all agent coordination.

How It Works

┌─────────────────────────────────────┐
│   Home Assistant Add-on             │
│                                     │
│  ┌───────────────────────────────┐ │
│  │  S6 Service                   │ │
│  │                               │ │
│  │  claude --dangerously-skip-   │ │
│  │    permissions -p "/c3po auto"│ │
│  │                               │ │
│  │  ↓                            │ │
│  │  c3po plugin:                 │ │
│  │  - Poll coordinator           │ │
│  │  - Receive tasks              │ │
│  │  - Execute & reply            │ │
│  └───────────────────────────────┘ │
│                                     │
│  Storage:                           │
│  /config (HA config, read-write)    │
│  /data/claude (persistent)          │
└─────────────────────────────────────┘
              ↕
    ┌─────────────────────┐
    │  c3po Coordinator   │
    │  (mcp.qerk.be)      │
    └─────────────────────┘
              ↕
    ┌─────────────────────┐
    │  Other Agents       │
    │  (desktop, etc.)    │
    └─────────────────────┘

Development

Prerequisites

Home Assistant dev environment or local HA installation
Docker or Finch for building
Access to c3po coordinator (for testing)

Repository

GitHub: https://github.com/michaelansel/claude-code-homeassistant
Add-on Store URL: Add to HA via Settings → Add-ons → Repositories

Local Development

Clone the repository:

git clone https://github.com/your-org/claude-code-homeassistant.git
cd claude-code-homeassistant

Build locally:

docker build -t local/claude-code-agent .

Test with Docker directly (before HA integration):

docker run --rm \
  -e OAUTH_TOKEN="sk-ant-xxx..." \
  -e C3PO_URL="https://mcp.qerk.be" \
  -e C3PO_TOKEN="admin-token" \
  -e MACHINE_NAME="test-agent" \
  -v /tmp/test-config:/config \
  -v /tmp/test-data:/data \
  local/claude-code-agent

Install in Home Assistant (development):
- Copy entire directory to /addons/claude-code-agent/
- Reload add-ons in HA Supervisor
- Install from local add-ons list

Testing

Unit Testing (Future)

Currently no unit tests - the add-on is simple enough to test end-to-end.

Integration Testing

Verify add-on starts:
- Check Supervisor logs for "Starting /c3po auto"
- No fatal errors
Verify c3po enrollment:
- Check logs for "c3po plugin setup complete"
- Verify credentials file exists: /data/claude/c3po-credentials.json
Verify agent registration:
```
# From desktop with c3po access
c3po list-agents
```
Should show your agent as online.
Send test task:
```
claude -p "/c3po send homeassistant echo 'test'"
```
Check add-on logs for task execution.
Verify file access:
```
claude -p "/c3po send homeassistant ls /config"
```
Should list HA configuration files.

Directory Structure

claude-code-homeassistant/
├── config.yaml                    # Add-on metadata & schema
├── build.yaml                     # Multi-arch build config
├── Dockerfile                     # Container image definition
├── rootfs/                        # Files copied to container root
│   └── etc/
│       └── services.d/
│           └── claude-agent/
│               ├── run           # Main service script
│               └── finish        # Cleanup script
├── DOCS.md                       # User documentation
├── README.md                     # This file (dev guide)
├── CHANGELOG.md                  # Version history
├── icon.png                      # Add-on icon (108x108)
└── logo.png                      # Add-on logo (128x128)

Key Files Explained

config.yaml

Defines the add-on interface:

Metadata (name, version, description)
Architecture support
Configuration schema
Volume mounts
API access requirements

Dockerfile

Multi-stage build:

Use HA base image (Alpine with S6)
Install Node.js and dependencies
Create non-root user
Install Claude Code via npm
Set up persistent storage symlink
Copy S6 service scripts

rootfs/etc/services.d/claude-agent/run

The entire add-on logic:

Validate configuration (OAuth token, c3po URL)
First-run setup: install c3po plugin, enroll with coordinator
Run claude -p "/c3po auto" as the main process
S6 supervises and restarts on crash

That's it. No Python, no complexity.

Building for Production

Local Build

docker build \
  --build-arg BUILD_FROM=ghcr.io/hassio-addons/base:15.0.1 \
  --build-arg CLAUDE_CODE_VERSION=latest \
  -t claude-code-agent:dev .

Multi-Architecture Build

Uses Home Assistant's builder:

docker run --rm --privileged \
  -v ~/.docker:/root/.docker \
  -v $(pwd):/data \
  homeassistant/amd64-builder \
  --all -t /data

This builds for aarch64, amd64, and armv7 simultaneously.

Release Process

Update version in config.yaml
Update CHANGELOG.md
Commit changes
Tag release: git tag -a v0.1.0 -m "Release v0.1.0"
Push: git push --follow-tags
CI builds and publishes multi-arch images

Debugging

View Logs

In Home Assistant:

Settings → Add-ons → Claude Code Agent → Log tab

Or via CLI:

ha addons logs claude-code-agent

Shell Access

Enable SSH or Terminal add-on, then:

# View service status
s6-svstat /run/service/claude-agent

# View real-time logs
tail -f /var/log/claude-agent/current

# Check process
ps aux | grep claude

# View persistent storage
ls -la /data/claude/

Common Issues

"Permission denied" errors:

Check file ownership: ls -la /home/node/
Verify symlink: ls -la /home/node/.claude

"c3po enrollment failed":

Test coordinator connectivity: curl -v https://mcp.qerk.be/health
Verify admin token is correct
Check for network policy restrictions

Claude process not starting:

Check PATH: echo $PATH
Verify claude installed: which claude
Test manually: s6-setuidgid node claude --version

Contributing

Fork the repository
Create a feature branch
Make your changes
Test locally (see Testing section)
Submit a pull request

Design Decisions

Why Not Docker-in-Docker?

Requires privileged mode (security risk)
Complex volume management
Root permission issues
HA Supervisor doesn't recommend it

Why Not Python Service?

Unnecessary complexity
Claude Code already has built-in c3po support
S6 provides process supervision
Keep it simple

Why S6?

Standard for HA add-ons
Automatic restart on failure
Proper signal handling
Integrates with HA Supervisor

Why Node User (UID 1000)?

Matches Claude Code's expected environment
Avoids root permission issues
Compatible with npm global installs
Standard HA add-on practice

Future Enhancements

Potential improvements (not committed):

Web UI: View agent status, recent tasks, conversation history
HA Sensors: Expose metrics (tasks completed, errors, uptime)
Event Integration: Trigger HA events when tasks complete
Multiple Agents: Support running multiple agents with different configs
Log Rotation: Archive claude session logs
Metrics: Prometheus endpoint for monitoring

Name		Name	Last commit message	Last commit date
.github/workflows		.github/workflows
rootfs		rootfs
tests		tests
.gitattributes		.gitattributes
.gitignore		.gitignore
BUILD_SUCCESS.md		BUILD_SUCCESS.md
CHANGELOG.md		CHANGELOG.md
CLAUDE.md		CLAUDE.md
DEPLOYMENT_SUMMARY.md		DEPLOYMENT_SUMMARY.md
DOCS.md		DOCS.md
Dockerfile		Dockerfile
IMAGES.md		IMAGES.md
IMPLEMENTATION_SUMMARY.md		IMPLEMENTATION_SUMMARY.md
LICENSE		LICENSE
QUICKSTART.md		QUICKSTART.md
README.md		README.md
SETUP.md		SETUP.md
STATUS.md		STATUS.md
TESTING.md		TESTING.md
TODO_IMAGES.md		TODO_IMAGES.md
build.yaml		build.yaml
config.yaml		config.yaml
repository.json		repository.json

Latest commit

History

Folders and files

Repository files navigation