GETTING STARTED
Set up your agent.
From zero to a running KithKit agent in about 10 minutes.
Prerequisites
Hardware
Any Mac
macOS Ventura 13+ recommended. Apple Silicon (M1/M2/M3/M4) or Intel. A Mac Mini is ideal for always-on agents — it runs quietly 24/7 — but a laptop works fine too.
RAM
Minimum 8 GB. 16 GB recommended, especially if you plan to run local embeddings for the vector memory system or enable voice features.
Required software
Node.js 22+
Install via Homebrew: brew install node, or download directly from nodejs.org. KithKit uses ESM modules — Node 22 is required.
npm
Ships with Node.js — no separate install needed. Used for installing the framework and its dependencies.
tmux
Used for persistent agent sessions that survive SSH disconnects and keep running between conversations. Install: brew install tmux
jq
JSON processing used in shell scripts and daemon interactions. Install: brew install jq
Claude Code CLI
The AI backbone for all agents. Install globally: npm install -g @anthropic-ai/claude-code. Requires either an Anthropic API key or a Claude Pro/Max subscription.
claude login. Pay-as-you-go via API key also works.
Optional — for integrations
Telegram Bot Token messaging
Get one from BotFather. Lets your agent send and receive messages over Telegram.
Microsoft 365 App Registration email
For reading and sending email via the Microsoft Graph API.
Fastmail Account email
Alternative email integration via the JMAP API. Works well for personal agents.
whisper.cpp + Kokoro ONNX voice
Speech-to-text and text-to-speech for local voice interaction. Requires a capable machine.
Installation
Clone the repository
Pull KithKit from GitHub and create your agent's home directory. Replace my-agent with whatever you want your directory named — this becomes your agent's working environment.
git clone https://github.com/RockaRhymeLLC/kithkit.git my-agent cd my-agent
Install dependencies
Install the daemon, better-sqlite3, and all framework dependencies. This takes about 30 seconds. The native SQLite module will compile for your platform during install.
npm install
better-sqlite3 fails to compile, ensure you have Xcode Command Line Tools: xcode-select --install
Initialize your agent
The init wizard walks you through creating your agent's config file and identity. You'll be asked for a name, a personality template, and a port number.
kithkit.config.yaml, identity.md, and the initial SQLite database (kithkit.db).
npx kithkit init # The wizard will ask you: # Agent name (e.g., "BMO", "Jarvis", "Friday") # Personality template (friendly / professional / custom) # Port number (default: 3847)
Start the daemon
This starts everything at once: the daemon (background HTTP server), a tmux session for your comms agent, and loads Claude Code with your agent's identity. All in one command.
./scripts/start-tmux.sh # This starts: # 1. Daemon — HTTP server on localhost:3847 # 2. Session — tmux session for your comms agent # 3. Claude — loaded with your identity.md
Verify everything is running
Run the health check script to confirm the daemon, database, and agent session are all up. If anything shows red, the troubleshooting guide covers common issues.
./scripts/health.sh # ✓ daemon running on :3847 # ✓ database kithkit.db (WAL mode) # ✓ session my-agent (tmux) # ✓ agent online — waiting for input
Talk to your agent
Attach to the tmux session to interact directly in the terminal, or hit the API to confirm the daemon is responding. Both work — the API is handy for scripting and health checks.
# Attach to your agent's session tmux attach -t my-agent # Detach when done (agent keeps running) # Press: Ctrl+B then D
curl http://localhost:3847/status # {"agent":"MyAgent","status":"online","uptime":42}
Configuration
The main config file is kithkit.config.yaml in your project root. The framework ships with sensible defaults in kithkit.defaults.yaml — your config overrides them via deep merge, so you only need to specify what you want to change.
agent: name: MyAgent identity_file: identity.md daemon: port: 3847 log_level: info # debug | info | warn | error log_dir: logs log_rotation: max_size_mb: 10 max_files: 5 scheduler: tasks: [] # Add cron/interval tasks here
kithkit.config.yaml take effect after a hot-reload or daemon restart. Hot-reload: curl -X POST http://localhost:3847/api/config/reload
What's next
Your agent is running. Here's where to go from here: