Content
# Tool List
Parent Compass is a local-first, single-user, offline-capable tool for child observation and PBL project workbench. The main entry point is through an AI agent that writes and maintains a local SQLite database; the web interface is primarily for auditing, browsing raw logs, insights, PBL projects, and development maps.
It is designed for local use or trusted intranet environments without default authentication. Do not expose it to the public internet.
## Suitable Scenarios
Parent Compass is designed for parents who want to use an AI agent as a home observation assistant. It does not grade your child or turn development into KPIs; instead, it helps you save daily fragments and allows the agent to organize traceable understanding and suggestions for further accompaniment from evidence.
Typical scenarios:
- **Recording daily observations**: Fragmented observations, such as a child repeatedly pouring water during bath time, building structures with blocks, or negotiating after conflicts with peers, can be written into structured observation logs by the agent.
- **Generating insights from logs**: The agent can connect multiple observations across dimensions like language, body, emotion, exploration, execution, creativity, social relationships, and adult environment, interpreting what development this behavior might indicate and retaining source evidence.
- **Discovering recent development areas**: The development map prioritizes abilities that the child has already demonstrated, is approaching, or may need support for, rather than listing a complete but static list of capabilities.
- **Turning interests into PBL mini-projects**: When a child shows sustained interest in topics like water, shadows, symbols, tools, rules, or role-playing, the agent can generate a lightweight project based on existing insights, including why it's suitable now, how to start, what materials are needed, and what to pay attention to.
- **Auditing AI-generated content**: The web interface is not the primary input method but a place for parents to review the agent's work. You can see raw logs, insights, projects, source snapshots, and development map relationships, and correct any inaccuracies.
- **Protecting family data**: Data is stored locally in a SQLite database by default, not relying on cloud accounts; suitable for local single-user or trusted intranet use.
## Compatible Agents
Parent Compass is not tied to a specific AI client. Common local agents can be integrated, such as Codex, Claude Code, OpenClaw, Hermes, etc.
Integration conditions are straightforward:
- The agent can configure the stdio MCP server.
- The agent can read or install `.agents/skills/` from this project.
- Parents provide observations and modifications to the agent, who then writes to the local database via MCP.
## Quick Start
For the agent's first deployment, use the installation guide skill from this repository:
```text
Please use the pbl-install-guide skill from this project to help deploy and connect Parent Compass: https://github.com/oralzl/parent-compass
```
Complete installation instructions are in [docs/agent-installation.md](docs/agent-installation.md).
```bash
npm install
npm run dev
```
Open the local address shown in the terminal, typically:
```text
http://127.0.0.1:3000
```
The first API or MCP call will initialize the SQLite schema and create an active child: `Default Child`. The web sidebar allows for light modification of the child's name.
`npm run setup` is still available but is an optional local preparation/diagnostic command:
```bash
npm run setup
```
It ensures the database and default child exist, then prints the database path, active child, token authentication status, and next steps.
## MCP Main Entry
Configure the MCP server for the agent, suggested to be named `parent-compass`:
```bash
npm run mcp
```
The MCP server uses stdio for local read/write operations on the default database:
```text
data/pbl-so.sqlite
```
Common tools include:
- `create_raw_log`
- `list_raw_logs`
- `create_insight`
- `list_insights`
- `create_pbl_project`
- `list_pbl_projects`
- `get_child_development_map`
- `list_tech_tree_nodes`
- `get_tech_tree_node`
Without an active child, MCP automatically prepares `Default Child`, so the agent's first call doesn't require manually creating a profile.
## Web Audit View
The web interface is for auditing and browsing:
- Parenting logs
- Parenting insights
- PBL projects
- Development maps
- Source snapshots for insights/projects
The web interface does not require a token by default. It requests the local API directly and triggers automatic initialization for an empty database.
## Optional Token Protection
If you place the web interface on a family LAN, Tailscale, NAS, or other non-local environment, you can manually set `LOCAL_AUTH_TOKEN`:
```bash
cat > .env.local <<'EOF'
LOCAL_AUTH_TOKEN=replace-with-a-long-random-token
DATABASE_URL=file:data/pbl-so.sqlite
EOF
```
After setting:
- API requests must include `Authorization: Bearer <token>`.
- The web interface's first request shows a token input page.
- MCP still uses local stdio, bypassing HTTP tokens.
For public internet protection, consider using reverse proxy authentication, Tailscale, Cloudflare Access, or Basic Auth. Do not expose instances without authentication.
## Data Files
- `data/pbl-so.sqlite`: Personal local data, should not be committed.
- `data/child-development-tech-tree.db`: Built-in child development capability map, can be updated with the repository.
When updating the built-in map, users can get the new map by `git pull`; personal observations, insights, and capability status remain in `data/pbl-so.sqlite`, not overwritten.
Maintain the map by keeping existing node IDs stable. Before deleting nodes, consider deprecation/disabling strategies to avoid orphan nodes referenced by user flags or insight links.
## Demo Data
Demo data is not automatically written by default. To experience the full interface, run:
```bash
npm run db:seed
```
Soft delete demo data:
```bash
npm run db:clear-demo
```
Demo data is marked with `metadata.demo = true` or equivalent; cleanup commands do not delete real data.
## API Examples
Default without token:
```bash
BASE=http://127.0.0.1:3000
curl "$BASE/api/children"
```
If `LOCAL_AUTH_TOKEN` is set:
```bash
TOKEN=your-local-token
BASE=http://127.0.0.1:3000
curl "$BASE/api/children" -H "Authorization: Bearer $TOKEN"
```
Create RawLog:
```bash
curl -X POST "$BASE/api/raw-logs" \
-H "Content-Type: application/json" \
${TOKEN:+-H "Authorization: Bearer $TOKEN"} \
-d '{
"content": "Repeatedly filled and emptied a cup during bath time.",
"source": "manual_web",
"scene": "Bath time",
"participants": ["Child", "Father"],
"metadata": {}
}'
```
Omitting `child_id` writes to the current active child.
## Verification
```bash
npm run typecheck
npm run verify
npm run build
```
Manual acceptance checklist in [docs/verification.md](docs/verification.md).
