Skip to main content
The Forge watches signals (git, filesystem, processes, webhooks) and applies rules to automatically manage quests and send notifications. You can also manage forge rules via the Companion chat using create_forge_rule, list_forge_rules, update_forge_rule, run_forge_rule, and delete_forge_rule.

​
Subcommands

​
forge create

grindxp forge create
Interactive wizard to create a new forge rule. Prompts for:
  • Trigger type: cron, signal, webhook, event, manual
  • Trigger config: cron expression, signal source, watched path, process pattern, etc.
  • Action type: queue-quest, log-to-vault, send-notification
  • Action config: questId, activity type, notification channel, etc.

​
forge list

grindxp forge list
Lists all forge rules with their trigger, action, enabled status, and last run time.

​
forge toggle

grindxp forge toggle
Select a rule to enable or disable. Disabled rules are skipped during forge ticks.

​
forge run

grindxp forge run
Manually trigger a single forge tick. Evaluates all enabled rules against current signals.

​
forge run-rule

grindxp forge run-rule <ruleId>
Run a specific forge rule immediately, regardless of its trigger type. Useful for testing without waiting for the next tick.

​
forge tick

grindxp forge tick
Same as forge run but outputs verbose debug output. Useful for debugging why a rule isn’t firing.

​
forge daemon

grindxp forge daemon
Starts the forge daemon as a foreground process. The daemon runs a tick on the configured interval (default 60s) and listens for real-time signals. For production use, manage the daemon via the gateway command which handles process lifecycle.

​
Trigger Types

TriggerDescription
cronEvaluated on a cron schedule (triggerConfig.cron, optional triggerConfig.timezone)
signalFires when a signal is detected: git commit, file change, or running process (triggerConfig.source = git|file|process)
webhookFires when the gateway receives a matching inbound event
eventFires on an internal application event
manualOnly fires when explicitly triggered via CLI or agent tool

​
Action Types

ActionDescription
queue-questRe-activates a quest by ID (actionConfig.questId)
log-to-vaultCreates and auto-completes a bounty quest, awarding XP (actionConfig.activityType, actionConfig.durationMinutes)
send-notificationSends a message via console, telegram, webhook, or whatsapp (actionConfig.channel, actionConfig.message)

​
Configuration Examples

Cron rule (daily recap notification via Telegram): 
{
  "name": "Daily recap",
  "triggerType": "cron",
  "triggerConfig": { "cron": "0 20 * * *", "timezone": "America/New_York" },
  "actionType": "send-notification",
  "actionConfig": {
    "channel": "telegram",
    "chatId": "YOUR_CHAT_ID",
    "message": "Time to log today's progress!"
  }
}
Signal rule (auto-log coding session on git commit): 
{
  "name": "Log coding on commit",
  "triggerType": "signal",
  "triggerConfig": { "source": "git" },
  "actionType": "log-to-vault",
  "actionConfig": { "activityType": "coding", "durationMinutes": 30 }
}
  • Forge Engine: internals and rule evaluation details
  • gateway: manage the gateway server that receives webhooks