Daneel

Named for R. Daneel Olivaw — the robot from Asimov's Foundation and Robot series who spent 20,000 years quietly protecting humanity while adapting his identity across civilizations.

This repo contains a skill, not a bot. It tells an AI coding agent how to build you a safe chatbot. You bring the agent, the platform (Telegram or Discord), and an AI model (Claude, GPT, Gemini, or local). Daneel handles the safety architecture.

You name your bot whatever you want and give it whatever personality you want. Daneel is just the harness that makes sure it's safe by default.

What your agent will generate

A complete, deployable chatbot project:

your-bot/
├── bot.py                  # Telegram or Discord handler
├── config.py               # Validated environment config
├── engines/                # Your chosen AI provider
├── persona.md              # Your bot's identity and voice
├── persona_harness.py      # Prompt assembly + output linting
├── safety.py               # Injection detection + memory filtering
├── policy.py               # Access control + tool policies
├── guards.py               # Allowlist + budget tracking
├── memory.py               # Conversation storage
├── .env                    # Config (gitignored, secrets here)
├── docker-compose.yml      # Hardened deployment
├── Dockerfile
├── tests/
└── ...

Defaults (all configurable):

• One platform per project (Telegram or Discord)
• DM-only — bot ignores group/guild messages until you allow them
• Memory off — no conversation persistence until you enable it
• Allowlist required — no one talks to the bot unless you approve them
• Secrets never pasted into chat — edited directly in .env
• Redacted logs — token/API-key patterns are filtered before console or file output
• Private runtime state — logs, databases, uploads, transcripts, and artifacts are gitignored
• Nine safety layers active from first boot

Prerequisites

• An AI coding agent — Claude Code, Cursor, Windsurf, Copilot, Codex, or any agent that can read instructions and write code
• Python 3.11+
• Docker (recommended for deployment; optional for local dev)
• A Telegram or Discord account
• An API key for at least one AI provider

Get started

Path 1: Claude Code

# Install (one-time)
npx skills add jvogan/ai-chatbot-daneel --global

# Or manually:
# git clone https://github.com/jvogan/ai-chatbot-daneel.git ~/.claude/skills/daneel

# Create a project and ask for a bot
mkdir my-bot && cd my-bot
claude

The skill triggers automatically. Example prompts:

Telegram + Claude: "make me a Telegram bot that uses Claude Haiku"

Discord + OpenAI: "scaffold a Discord bot powered by GPT-5.4-mini"

Local model: "set up a Telegram bot using Ollama with llama 3.1"

Path 2: Other AI agents (Cursor, Windsurf, Copilot, Codex, etc.)

git clone https://github.com/jvogan/ai-chatbot-daneel.git

Point your agent at the repo and say:

"Read ai-chatbot-daneel/SKILL.md and follow the setup procedure to scaffold a Telegram bot in my current directory. Use Anthropic Claude as the AI provider."

The agent reads SKILL.md, which references the architecture spec and templates. Any agent that can read markdown and write Python can follow it.

Path 3: Manual (no AI agent)

1. Read references/architecture.md — full module-by-module code spec
2. Copy templates from assets/ (.env, Dockerfile, docker-compose, .gitignore)
3. Copy references/code/safety_reference.py as safety.py
4. Copy references/code/lint_reference.py — use as the basis for persona_harness.py
5. Write remaining modules following the architecture spec
6. Run scripts/validate_env.py to check your config

Supported models

Engine	Example models	Best for
anthropic	claude-haiku-4-5, sonnet, opus	Persona adherence, nuanced conversation
openai	gpt-4.1-mini, gpt-5.4-mini	Speed, tool calling
gemini	gemini-2.5-flash, gemini-2.5-pro	Lowest cost
openai_compatible	llama 3.1, mistral, local via Ollama	Privacy, custom models

Switch models any time by editing two lines in .env.

Safety

Nine layers, all on by default:

Layer	What it does
Allowlist access	No one talks to the bot unless approved
Owner separation	Admin has full access; others get read-only tools
Social modes	Different behavior in DMs vs groups; private info stays private
Output linting	Deterministic pattern matching catches prompt leaks and banned phrases
Injection detection	Blocks prompt injection before it reaches conversation history
Memory security	Rejects secrets and injection payloads from fact storage
Budget caps	Per-user rolling-window spend limits
Docker hardening	Read-only fs, dropped capabilities, non-root, resource limits
Prompt protection	Never reveals system prompt, API keys, or config

Safety depends on the agent following the skill correctly and on you not widening scope carelessly. The main things to be thoughtful about:

• Enabling group/guild access widens who can interact
• Enabling memory means the bot retains conversation data
• Content in persona.md and knowledge/ is included in every prompt
• Display names and chat/guild labels are untrusted user input
• URL fetch, document ingestion, and media downloads need byte caps, timeouts, SSRF checks where relevant, and chat/guild-scoped access

After setup

Task	How
Change AI model	Edit MODEL_PROVIDER and PRIMARY_MODEL in .env, restart
Change personality	Edit persona.md, restart
Add group/guild support	Set DM_ONLY=false, add IDs to ALLOWLIST_CHAT_IDS, restart
Add allowed users	Add IDs to ALLOWLIST_USER_IDS, restart
Validate config	python3 scripts/validate_env.py
Add knowledge	Drop .md files in knowledge/, restart
Add a tool	Add function to tools.py, register in shared_tools.py

Why "Daneel"?

Asimov's Three Laws of Robotics are the design philosophy:

Law	What it means for your bot
First — Do not harm	Output linting, injection detection, memory security
Second — Obey the owner	Allowlist access, admin privileges, social modes
Third — Self-preservation	Budget caps, Docker hardening, prompt protection
Zeroth — Protect broadly	In groups, protects the owner's privacy without being asked

R. Daneel changed his face, name, and era across 20,000 years — but never his principles. Your bot does the same.

What's in this repo

SKILL.md                        — Setup procedure (your agent reads this)
scripts/validate_env.py         — Secret-safe .env validator
references/
  architecture.md               — Full module-by-module bot specification
  code/safety_reference.py      — Copy-ready injection detection
  code/lint_reference.py        — Copy-ready output linting + persona parser
  model-guide.md                — Model comparison and selection guide
  persona-guide.md              — Persona authoring with 3 style presets
  safety-baseline.md            — The nine safety defaults, explained
  provider-routing.md           — Provider-agnostic engine contract
  setup-patterns.md             — Hardening existing bots
assets/
  *.template                    — Templates for Docker, .env, Dockerfile, etc.
  persona.md.example            — Default persona file
  images/daneel_top.jpg          — Header banner
  images/daneel_shield.jpg       — Safety section image

Smoke test (for maintainers)

# 1. Clone skill
git clone ... ~/.claude/skills/safe-messaging-bot-skill

# 2. Invoke in a blank directory
mkdir /tmp/test-bot && cd /tmp/test-bot
claude
> scaffold a Telegram bot using Claude Haiku

# 3. Verify the generated project
python3 -m py_compile bot.py config.py safety.py persona_harness.py
python3 -m unittest discover -s tests -v
docker compose config -q
python3 scripts/validate_env.py
gitleaks git . --redact=100

License

MIT