OpenSkillIndex← back to search
claude-code

Samara-main services

/services - Service Toggle System

install
source · Clone the upstream repo
git clone https://github.com/claudeaceae/samara-main
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/claudeaceae/samara-main "$T" && mkdir -p ~/.claude/skills && cp -r "$T/.claude/skills/services" ~/.claude/skills/claudeaceae-samara-main-services && rm -rf "$T"
manifest: .claude/skills/services/SKILL.md
source content

/services - Service Toggle System

Manage which services are active in the Samara organism. Services can be toggled on/off without deleting code - they're simply unplugged from the wake cycle, sense routing, and launchd scheduling.

Quick Commands

# List all services with current status
~/.claude-mind/system/bin/service-toggle list

# Toggle a service
~/.claude-mind/system/bin/service-toggle <service> on|off|status

Available Services

ServiceDescriptionlaunchd Agents
x
X/Twitter mentions, replies, postingx-watcher, x-engage
bluesky
Bluesky notifications, DMs, postingbluesky-watcher, bluesky-engage
github
GitHub notificationsgithub-watcher
wallet
Crypto wallet monitoringwallet-watcher
meeting
Calendar meeting prep/debriefmeeting-check
webhook
External webhook eventswebhook-receiver
location
Location trackinglocation-receiver
browserHistory
Browser history from É's devices(client-side)
notesWatcher
Apple Notes scratchpad polling in Samara.app(in-app only, no launchd agent)

How It Works

The service toggle system has three layers:

1. Config (
~/.claude-mind/system/config.json
)

{
  "services": {
    "x": false,
    "bluesky": false,
    "github": true,
    "wallet": true,
    "meeting": true,
    "webhook": true,
    "location": true,
    "browserHistory": true,
    "notesWatcher": false
  }
}

2. SenseRouter (Samara.app)

When Samara starts, 

SenseRouter.registerDefaultHandlers()
checks 
config.servicesConfig.isEnabled()
for each service. Disabled services don't get handlers registered, so their sense events are ignored.

3. launchd Agents

The 

service-toggle
script also manages launchd agents - when you disable a service, it unloads the corresponding agents so they stop polling/watching.

Usage Examples

Check current status

~/.claude-mind/system/bin/service-toggle list

Output:

Service Status:
---------------
x            config: false  launchd: unloaded
bluesky      config: false  launchd: unloaded
github       config: true   launchd: loaded
...

Disable a service

~/.claude-mind/system/bin/service-toggle x off

This will:

  1. Set 
    services.x = false
    in config.json
  2. Unload 
    com.claude.x-watcher
    and 
    com.claude.x-engage
    from launchd
  3. Print a reminder to restart Samara.app for handler changes

Re-enable a service

~/.claude-mind/system/bin/service-toggle bluesky on

This will:

  1. Set 
    services.bluesky = true
    in config.json
  2. Load the bluesky launchd agents
  3. Print a reminder to restart Samara.app

Restart Samara.app (for handler changes)

pkill -x Samara && sleep 1 && open -a Samara

Or use the update-samara script if you also have code changes.

Important Notes

  • Non-destructive: Disabling a service doesn't delete any code - it just unplugs it
  • Restart required: Samara.app reads config at startup, so restart after toggling for handler changes to take effect
  • launchd is immediate: The launchd agents are loaded/unloaded immediately
  • Defaults to enabled: Services not specified in config default to enabled (backward compatible), except 
    notesWatcher
    which defaults to 
    false

Files

FilePurpose
~/.claude-mind/system/config.json
Runtime config with 
services
section
Samara/Samara/Configuration.swift
ServicesConfig
struct and 
isEnabled()
method
Samara/Samara/Mind/SenseRouter.swift
Checks config before registering handlers
scripts/service-toggle
CLI for toggling services

When to Use This

Use the service toggle system when you want to:

  • Reduce token usage by disabling services you're not actively using
  • Pause a noisy service temporarily without losing the capability
  • Debug by isolating which services are active
  • Focus by limiting which channels are monitored

The system is designed for clean plug/unplug without code changes.

Implementing New Services (REQUIRED)

All new senses and services MUST be toggleable. This is a hard requirement for any capability that polls external services, processes sense events, contributes to memory, or consumes tokens.

Checklist for New Services

  1. Configuration.swift - Add to 

    ServicesConfig
    :

    let myservice: Bool?

// In isEnabled():
case "myservice": return myservice ?? true

  2. SenseRouter.swift - Guard the handler:

    if services.isEnabled("myservice") {
    handlers["myservice"] = { [weak self] event in
        self?.handleMyServiceEvent(event)
    }
}

  3. scripts/service-toggle - Register the service:

    # Add to SERVICES list:
SERVICES="x bluesky github wallet meeting webhook location myservice"

# Add to get_agents():
myservice) echo "com.claude.myservice-watcher" ;;

  4. config.json - Add default (usually 

    true
    ):

    "services": {
  "myservice": true
}

  5. This file - Add to the Available Services table above

Why This Matters

The collaborator needs the ability to cleanly disable any service without touching code. This prevents:

  • Unwanted token consumption
  • Noise from services that aren't actively needed
  • Tight coupling that makes the system harder to manage

See existing implementations (x, bluesky, wallet, meeting) for reference patterns.