Stint Agent

The official CLI agent for Stint — a lightweight daemon that bridges the Stint web app and your local git repositories, enabling automatic commit execution and real-time repo syncing.

Features

• 🔐 Secure authentication with OAuth
• 🔄 Real-time WebSocket connection to Stint
• 📦 Automatic commit execution
• 🔍 Repository status syncing
• 🖥️ Background daemon process
• 📝 Comprehensive logging and filtering
• 📊 Interactive status dashboard
• 🚀 Multiple release channels (stable/beta/nightly)
• 🔍 Built-in environment diagnostics
• 📈 Resource usage monitoring
• 📁 File selection for commits (sync changed files to web app)

For detailed feature documentation, see the Features Guide.

Installation

npm install -g @gowelle/stint-agent
# or
pnpm add -g @gowelle/stint-agent

Quick Start

# Authenticate with Stint
stint login

# Check your authentication status
stint whoami

# Link a project (or create a new one)
cd /path/to/your/project
stint link

# Start the daemon
stint daemon start

# Check daemon status
stint daemon status

Commands

General

| Command | Description | | ----------------------------- | ---------------------------------- | | stint --version, stint -V | Show current agent version | | stint --help, stint -h | Show help information | | stint update | Update agent to the latest version |

Authentication

| Command | Description | | -------------- | ------------------------------------------------- | | stint login | Authenticate with Stint (opens browser for OAuth) | | stint logout | Remove stored credentials | | stint whoami | Show current user and machine information |

Daemon Lifecycle

| Command | Description | | ------------------------------- | --------------------------------------------------------- | | stint install | Register daemon to run on system startup (Login required) | | stint uninstall | Remove daemon from system startup | | stint daemon start | Start background daemon manually | | stint daemon stop | Stop daemon gracefully | | stint daemon status | Check if daemon is running | | stint daemon logs [--lines N] | View daemon logs (default: 50 lines) | | stint daemon restart | Restart the daemon |

Project Management

| Command | Description | | ---------------------------- | --------------------------------------------------------------- | | stint link | Link current directory to a Stint project (or create a new one) | | stint unlink [--force] | Remove project link | | stint status [--dashboard] | Show status (use -d for interactive dashboard) | | stint sync | Manually sync repository information to server |

Commit Operations

| Command | Description | | ------------------- | ------------------------------------------------------- | | stint commits | List pending commits for this repository | | stint commit <id> | Execute a specific pending commit (supports partial ID) |

stint commit Options:

| Option | Description | | -------------- | ------------------------------------------------- | | --auto-stage | Automatically stage files specified in the commit | | --push | Push changes to remote after committing | | --force | Skip file validation warnings |

Commit Workflow Controls

Stint supports advanced commit controls configured via the web dashboard:

1. Commit Templates: Enforce message conventions (e.g., conventional commits).
2. Pre-commit Hooks: Automatically run local commands (linting, tests) before the agent executes a commit.
   • Blocking: Configure hooks to prevent commit on failure.
   • Timeouts: Configurable timeout execution.

Configure these securely in your Project Settings on stint.codes.

Complete Workflow

# 1. Install and authenticate
npm install -g @gowelle/stint-agent
stint login

# 2. Link your project
cd /path/to/your/project
stint link

# 3. Start the daemon
stint daemon start

# 4. Check status
stint status

# Now commits approved in the web app will execute automatically!

Configuration

Desktop Notifications

The daemon sends desktop notifications for important events. Notifications can be controlled globally or per-category.

Notification Categories

| Category | Events | Default | | ------------- | ---------------------------------------- | ------- | | commits | Commit approved, pending, pushed, failed | ✅ On | | sync | Sync requested, project updated | ❌ Off | | suggestions | New AI suggestions | ✅ On |

Note: sync is disabled by default because these events fire frequently during active development.

Toggle All Notifications

# Disable all notifications
stint config set notifications.enabled false

# Enable all notifications
stint config set notifications.enabled true

Toggle by Category

# Disable sync notifications (noisy during development)
stint config set notifications.sync false

# Enable commit notifications
stint config set notifications.commits true

# Disable suggestion notifications
stint config set notifications.suggestions false

View Current Settings

stint config list

Note: Events are still logged even when notifications are disabled.

Troubleshooting

For comprehensive troubleshooting help, see the Troubleshooting Guide.

Quick Tips

"Not authenticated" error

stint login

Daemon won't start

stint daemon status        # Check if already running
stint daemon logs          # Check logs for errors
stint daemon restart       # Restart daemon

For detailed solutions, including:

• Connection issues (WebSocket, API, Circuit Breaker)
• Daemon problems (crashes, autostart)
• Authentication errors
• Git operation failures
• Platform-specific issues (Windows, macOS, Linux)

See the Troubleshooting Guide.

Logging

Logs are stored in your system's config directory:

| Platform | Log Location | | ----------- | ----------------------------------- | | macOS | ~/.config/stint/logs/ | | Linux | ~/.config/stint/logs/ | | Windows | %USERPROFILE%\.config\stint\logs\ |

Log files:

• agent.log - General CLI operations
• daemon.log - Daemon process logs
• error.log - Error details

Development

git clone https://github.com/gowelle/stint-agent.git
cd stint-agent
pnpm install
pnpm build
pnpm dev    # Watch mode

Security

• Tokens are encrypted at rest using machine-specific keys
• All API communication uses HTTPS
• WebSocket connections are authenticated
• Git operations are restricted to linked directories

License

MIT © Gowelle John

Support

For issues and questions, please open an issue.