Jean-Claude

Jean-Claude is a reusable family assistant runtime for homeschool management. For family-facing guidance, see ../README.md. For agent orientation, see ../AGENTS.md.

Overview

Jean-Claude is an LLM-powered assistant that manages homeschool records, generates lesson plans, tracks compliance, and handles day-to-day family logistics. It runs on a Raspberry Pi and serves a browser chat app, an MCP server for Claude Desktop and CLI, and a terminal client.

The system is built on two ideas:

1. Markdown is the API. All family data and assistant behavior lives in human-readable markdown files. Any LLM that can read files can operate the system, with or without the MCP server running.

2. Skills are configuration, not code. Behavioral intelligence is defined in standalone skill files (homeschool/skills/*.md), not in Python. The runtime loads them at call time. Updating a skill file changes behavior immediately with no code change or restart.

Architecture

jean-claude/
  IDENTITY.md         Persona and values
  AGENTS.md           Conventions, startup sequence, skill routing
  ARCHITECTURE.md     Ownership model and runtime boundaries
  jc_core/            Config, providers, retrieval, validation, locking
  jc_mcp/             FastMCP server, prompt assembly, tool executor, paths
  jc_web/             NiceGUI browser chat client
  scripts/            Sync, heartbeat, deployment helpers
  tests/              Test suite
  docs/               MCP, web, remote access, design docs

Skill definitions live in the sibling homeschool/skills/ directory (private, family-specific). The runtime loads them at call time from there.

Key principle

Skill files (homeschool/skills/*.md) are the canonical intelligence layer. The MCP server loads them at call time. No domain knowledge lives exclusively in Python. If the MCP server goes down, any LLM can read the skill files and operate the system directly.

STATUS.md is the system hub for current week, compliance deadlines, and system health. homeschool/resources/notes.md is the operational backlog for deferred work and planning-relevant observations. homeschool/resources/data-model.md is the canonical file-class manifest. The runtime should read all three at startup so file ownership and update mode are clear from the first turn.

Homeschool data dependency

This runtime expects a sibling homeschool/ directory at the same level (both under ~/family/). At minimum, the following structure is required:

homeschool/
  STATUS.md               Current week, hours, compliance deadlines
  resources/notes.md      Deferred work and planning-relevant observations
  resources/data-model.md Canonical file classes, owners, update modes
  skills/                 Skill definitions (*.md, one per skill)
  weeks/                  Week logs (week-NN.md)
  family/                 Family member profiles (*.md)
  resources/              Reference material and format specs
  compliance/             District documents
  reading/                Reading register (current.md, history.md, maybe.md)
  portfolio/              Work samples and intake drop zone
  portfolio/intake/       Drop zone for new photos
  mail/                   Processed district mail

See ARCHITECTURE.md for the full ownership model and AGENTS.md for the skill routing table.

Install

cd ~/family/jean-claude
python3 -m venv .venv
.venv/bin/pip install -e '.[dev]'

Run

Managed services (systemd user units):

• jean-claude.service — web app on 127.0.0.1:8000 (behind Cloudflare Tunnel)
• jean-claude-mcp.service — MCP on Tailscale IP :8765

Manual:

.venv/bin/jean-claude-web          # browser app
.venv/bin/jean-claude-mcp-http     # hosted MCP
.venv/bin/jean-claude-mcp          # stdio MCP (for Claude Desktop local)

Test

.venv/bin/python -m pytest tests/ -q

Cron

• sync_all.py — rclone bisync + Google Drive doc conversion (every 10 min)
• heartbeat.py — checks defined in homeschool/resources/heartbeat.md (every 10 min, offset 2 min after sync)

Docs

Document	Purpose
docs/mcp.md	MCP server setup and client configuration
docs/web.md	Browser app behavior
docs/remote-access.md	Tailscale and Cloudflare networking
docs/providers.md	Model provider configuration
docs/gdrive-sync.md	Google Drive sync automation
docs/skills-canonical-plan.md	Design rationale for skills-as-markdown