CiC Check-in Agent

A Node.js CLI agent that posts AI-generated work check-ins to the Coding in Color Slack channel. Runs on Windows (VS Code) and supports a live loop mode that checks every 60 seconds.

Prerequisites

• Node.js 18+
• Environment variables: OPENROUTER_API_KEY, SLACK_USER_TOKEN, GITHUB_TOKEN

Setup (Windows PowerShell)

1. Install dependencies

cd cic_checkin_agent
npm install

2. Set environment variables

$env:OPENROUTER_API_KEY = "your-openrouter-key"
$env:SLACK_USER_TOKEN = "your-slack-user-oauth-token"
$env:GITHUB_TOKEN = "your-github-personal-access-token"

SLACK_USER_TOKEN posts as you; if it's channel-scoped, no channel ID is needed. Otherwise, set the channel via checkin_agent set --channel C01234567 after init.

To make env vars persistent (current user), add to your PowerShell profile or use System Environment Variables.

3. Initialize the agent

node index.js init
node index.js init --github ClergeF

Optionally set your GitHub handle during init. This creates %USERPROFILE%\.cic_checkin_agent\ with:

• config.json (schedule, model, github_handle, repos, scan settings)
• state.json (daily check-in slot state)

4. Set GitHub handle and add repos

# Set GitHub handle (if not done during init)
node index.js set --github ClergeF

# Interactive: fetch your repos and pick which to add
node index.js select-repos

# Or add manually by owner/repo
node index.js add-repo ClergeF/my-project

5. Test one-shot auto

node index.js auto

Checks if it's time to post. If not eligible, prints next scheduled time.

6. Start the loop (live agent)

node index.js auto --loop

Runs continuously, checking every 60 seconds. Press Ctrl+C to stop.

Commands

| Command | Description | |---------|-------------| | checkin_agent init | Create config and state; verify env vars; optional --github Handle | | checkin_agent set | Update task, notes, model, scan, channel, or github (e.g. --github ClergeF) | | checkin_agent reset | Reset today's slots; use --full to clear repo scan memory | | checkin_agent chat | Interactive LLM chat (no Slack) | | checkin_agent status | Show state, next check-in, GitHub handle, repos | | checkin_agent history | Show recent posted check-ins | | checkin_agent select-repos | Interactive: fetch GitHub repos and pick which to add | | checkin_agent add-repo <owner/repo> | Add a GitHub repo (e.g. ClergeF/my-project) | | checkin_agent remove-repo <name> | Remove a repo by full_name or short name | | checkin_agent list-repos | List approved GitHub repos | | checkin_agent scan-work | Fetch recent commits from GitHub and print summary | | checkin_agent test | Dry-run: generate message without posting (no Slack, no schedule wait) | | checkin_agent test-loop | Test the loop: cycles through all 3 slots (16:45, 19:30, 22:00) every 15s; no Slack post | | checkin_agent checkin | Force a check-in now | | checkin_agent auto | One-shot: post if eligible | | checkin_agent auto --loop | Run forever, check every 60s |

Running as checkin_agent globally

npm link
checkin_agent init
checkin_agent status
checkin_agent auto --loop

Check-in schedule

Default times (local machine time):

• 4:45 PM (16:45)
• 7:30 PM (19:30)
• 10:00 PM (22:00)

Eligibility window: ±2 minutes. At most one post per slot per day.

GitHub token

Create a Personal Access Token at GitHub Settings > Developer settings > Personal access tokens. Use classic or fine-grained; for private repos, enable repo scope (classic) or contents: read (fine-grained).

Data directory

All files live in %USERPROFILE%\.cic_checkin_agent\:

• config.json - Settings, schedule, repos
• state.json - Today's slots, last post time
• history.jsonl - Debug log of posted messages
• error.log - Errors