lev-os/agents/agentping

Name: agentping
Author: lev-os

Claude Code and agent skill by lev-os/agents

Trust tier 3

community

Source check pending

Checking that the SKILL.md file is still in the repository.

Structured agent-to-human pings for approvals, selections, and open questions across surfaces. Use for human-in-the-loop or async feedback.

Install

npx vskill@latest install lev-os/agents/agentping

SKILL.md

AgentPing - Agent-Human Interaction Protocol

Overview

AgentPing provides structured communication between AI agents and humans. Instead of unstructured text, agents create typed "pings" that render appropriately across surfaces (CLI, web UI, Slack, Telegram).

Phase 2 Status (Production Ready):

✅ 198 React components with Cyber-Premium dark theme
✅ 38 E2E tests passing across 5 browsers (Chromium, Firefox, WebKit, Mobile)
✅ Full ADA compliance with WCAG 2.1 AA standards
✅ Responsive design (mobile, tablet, desktop)
✅ Tailwind CSS v4 integration
✅ Storybook documentation for P0/P1 components

Quick Decision Tree

Agent needs human input?
|
+-> Simple yes/no?
|   +-> Use `agentping approve "Deploy to production?"`
|
+-> Multiple options?
|   +-> Use `agentping select --options "A,B,C" "Choose approach"`
|
+-> Open-ended question?
|   +-> Use `agentping ask "What should I focus on?"`
|
+-> Multiple steps to approve?
|   +-> Use `agentping approve-steps --file steps.json`
|
+-> Just informing (no response)?
    +-> Use `agentping notify "Task completed"`

Installation

bash

# Via npm (global)
npm install -g @agentping/cli
 
# Via pnpm (monorepo)
pnpm add @agentping/cli
 
# Verify
agentping --version

Core Commands

1. Approval (Yes/No)

Request approval for an action:

bash

# Basic approval
agentping approve "Deploy to production?"
 
# With JSON output for agents
agentping approve "Run database migration?" --json
 
# With timeout
agentping approve "Execute build?" --timeout 60
 
# Exit codes: 0=approved, 1=denied, 2=timeout, 3=error

JSON Output:

json

{
  "approved": true,
  "action": "approved",
  "enrichment": {
    "directives": [
      {"type": "constraint", "rule": "run during low-traffic hours"}
    ],
    "notes": "approved for staging first"
  }
}

2. Ask (Freeform Question)

Ask a question and wait for response:

bash

# Open-ended question
agentping ask "What should I prioritize?"
 
# With suggested options
agentping ask "Which approach?" --options "A,B,C"
 
# JSON output for parsing
agentping ask "Database choice?" --options "postgres,mysql,sqlite" --json

JSON Output:

json

{
  "action": "answered",
  "data": {
    "type": "answer",
    "value": "postgres"
  },
  "enrichment": {
    "notes": "we already use postgres in prod"
  }
}

3. Select (Multiple Choice)

Present options for selection:

bash

# Single selection
agentping select --title "Choose framework" --options "React,Vue,Svelte"
 
# Multiple selection allowed
agentping select --title "Select features" --options "auth,api,ui" --multiple
 
# From JSON file
agentping select --file options.json --json

Options JSON format:

json

{
  "title": "Choose deployment target",
  "options": [
    {"id": "prod", "label": "Production", "description": "Live environment"},
    {"id": "staging", "label": "Staging", "description": "Pre-production"}
  ],
  "allowMultiple": false
}

4. Step Approval (Multi-Step)

Request approval for multiple steps:

bash

agentping approve-steps --file steps.json --json

Steps JSON format:

json

{
  "title": "Database Migration Plan",
  "context": "Migrating to new schema version",
  "steps": [
    {"id": "backup", "description": "Create backup", "risk": "low", "reversible": true},
    {"id": "migrate", "description": "Run migration", "risk": "medium", "reversible": true},
    {"id": "verify", "description": "Verify integrity", "risk": "low", "reversible": true}
  ],
  "allowPartial": true
}

JSON Output:

json

{
  "action": "selected",
  "data": {
    "type": "step_approval",
    "approvedSteps": ["backup", "verify"],
    "deniedSteps": ["migrate"]
  },
  "enrichment": {
    "directives": [
      {"type": "constraint", "rule": "wait for QA sign-off before migrate"}
    ]
  }
}

5. Notify (Fire-and-Forget)

Send notification without waiting for response:

bash

# Info notification
agentping notify "Build completed successfully"
 
# Warning
agentping notify --level warning "Tests are slow (>5m)"
 
# Error
agentping notify --level error "Deployment failed"

6. Daemon Management

Control the AgentPing daemon:

bash

# Start daemon
agentping daemon start
 
# Check status
agentping daemon status
 
# Stop daemon
agentping daemon stop
 
# Restart
agentping daemon restart

Web UI Development

Running the Development Server

bash

# Start daemon (in background)
cd packages/adapters/daemon
pnpm dev &
 
# Start web UI (in foreground)
cd packages/adapters/web-ui
pnpm dev
 
# Open browser to http://localhost:7891

Running Storybook

bash

cd packages/adapters/web-ui
pnpm storybook
 
# Open browser to http://localhost:6006

Available Stories:

P0 Components: Badge, Spinner, StatusIndicator, ProgressBar, ToggleSwitch, SearchInput, TextArea, Slider, DatePicker, MultiSelect
P1 Components: PingCard, StepChecklist, SelectionList, EnrichmentPanel, QuickActions

See Component Reference for full inventory.

Running E2E Tests

bash

# Install Playwright browsers
npx playwright install
 
# Build required packages
pnpm --filter @agentping/core build
pnpm --filter @agentping/storage-sqlite build
pnpm --filter @agentping/http-api build
pnpm --filter @agentping/daemon build
 
# Run E2E tests (38 tests × 5 browsers = 190 test runs)
cd packages/adapters/web-ui
pnpm test:e2e
 
# View HTML report
npx playwright show-report

Test Coverage:

All 10 ping types (Notification, Approval, Question, Selection, StepApproval, Research, Review, TaskWorkflow, Secret, Custom)
All P1 components (PingCard, StepChecklist, SelectionList, QuickActions, EnrichmentPanel)
Responsive layouts (mobile, tablet, desktop)
Keyboard navigation (j/k for navigation, 'a' for approve)
Accessibility (ARIA roles, screen reader support)

Agent-First JSON Interface

All commands support --json flag for structured output. Agents should:

Always use --json flag
Parse exit codes: 0=success, 1=denied, 2=timeout, 3=error
Handle enrichment directives in responses

Input via stdin

bash

# Pipe JSON input
echo '{"title":"Deploy?","action":"deploy to prod"}' | agentping approve --stdin --json
 
# From file
cat ping.json | agentping approve --stdin --json

Environment Variables

bash

AGENTPING_URL=http://localhost:7890  # API endpoint
AGENTPING_TIMEOUT=300                # Default timeout (seconds)
AGENTPING_AGENT_ID=my-agent          # Default agent ID
AGENTPING_SESSION_ID=session-123     # Default session ID

Ping Types Reference

Type	Use Case	Response
`notification`	FYI, no response	Auto-dismissed
`question`	Open-ended query	Text answer
`approval`	Yes/no decision	approved/denied
`step_approval`	Multi-step approval	Selected steps
`selection`	Pick from options	Selected IDs
`research_request`	Research direction	Direction IDs
`review_request`	Review content	Feedback
`secret`	Sensitive input	Masked value
`custom`	Extensible	Custom data

Directive Types

Humans can enrich responses with directives:

Directive	Purpose	Example
`focus_on`	Direct attention	`{"type":"focus_on","target":"auth flow"}`
`skip`	Ignore something	`{"type":"skip","target":"unit tests"}`
`constraint`	Add rule	`{"type":"constraint","rule":"no breaking changes"}`
`prioritize`	Set priority	`{"type":"prioritize","items":["security","perf"]}`
`timeline`	Time constraint	`{"type":"timeline","deadline":"EOD","flexibility":"soft"}`
`reference`	Provide link	`{"type":"reference","url":"https://..."}`
`alternative`	Suggest option	`{"type":"alternative","suggestion":"use Redis"}`

Design System

AgentPing uses the Cyber-Premium dark theme with:

Background: Deep black (#050505) with subtle elevation layers
Text: High-contrast (#ededed primary, #a1a1aa secondary)
Accents: Neon cyan (#00e5ff), green (#00ff9d), pink (#ff2a6d), amber (#ffb800)
Effects: Glassmorphism, neon glows, smooth animations
Typography: Inter (sans), JetBrains Mono (code)

See Design Standards for complete reference.

Accessibility (ADA Compliance)

All components meet WCAG 2.1 AA standards:

✅ Contrast ratios: 4.5:1 (normal text), 3:1 (large text, interactive)
✅ Focus indicators: 2px cyan outline on keyboard navigation
✅ Touch targets: 44×44px minimum (mobile), 32px (desktop)
✅ Screen reader support: ARIA roles, labels, live regions
✅ Keyboard navigation: Tab, Enter/Space, Escape, Arrow keys
✅ Reduced motion: Respects prefers-reduced-motion

See Design Standards for component-specific ADA checklists.

Adapter Development

Create custom adapters for new platforms:

bash

# Generate adapter scaffold
agentping adapter create --name myplatform --template default

This creates:

adapters/myplatform/
+-- parser.ts      # Message -> PingSpec
+-- renderer.ts    # Response -> Native format
+-- config.yaml    # Platform settings
+-- index.ts       # Barrel export

Parser Interface

typescript

interface IInteractionParser {
  readonly name: string;
  readonly priority: number;  // Higher = tried first
  canParse(ping: Ping): boolean;
  parse(ping: Ping): ParsedInteraction;
}

ParsedInteraction Output

typescript

interface ParsedInteraction {
  interactionType: string;      // UI component hint
  quickActions: QuickAction[];  // 1-click responses
  uiHints: Record<string, unknown>;
  fallbackText: string;         // Text-only fallback
  fallbackOptions: string[];    // Simple options
}

Error Handling

Exit codes:

0 - Success (approved/answered)
1 - Denied/rejected
2 - Timeout
3 - Error (network, validation, etc.)

Error JSON format:

json

{
  "error": true,
  "code": "TIMEOUT",
  "message": "Response timeout after 300s",
  "pingId": "ping-abc123"
}

Examples for AI Agents

Claude Code Integration

bash

# Before destructive operation
result=$(agentping approve "Delete 47 files from /src?" --json)
if [ $? -eq 0 ]; then
  rm -rf /src/old/*
fi
 
# Get user direction
direction=$(agentping ask "Which feature should I implement first?" \
  --options "auth,api,dashboard" --json | jq -r '.data.value')

Programmatic (TypeScript)

typescript

import { PingService } from '@agentping/core';
const service = new PingService(store, parsers);
const ping = await service.createPing({
  agentId: 'my-agent',
  agentName: 'My Agent',
  sessionId: 'session-123',
  payload: {
    type: 'approval',
    title: 'Deploy to production?',
    action: 'deploy',
    risk: 'high'
  }
});
const response = await service.waitForResponse(ping.id, 300000);
if (response?.action === 'approved') {
  // proceed
}

Troubleshooting

Daemon not running

bash

agentping daemon status
agentping daemon start

Timeout issues

bash

# Increase timeout
agentping approve "Long decision?" --timeout 600

Connection refused

bash

# Check API endpoint
curl http://localhost:7890/health

E2E tests failing

bash

# Rebuild core packages
pnpm --filter @agentping/core build
pnpm --filter @agentping/storage-sqlite build
pnpm --filter @agentping/http-api build
pnpm --filter @agentping/daemon build
 
# Ensure servers are running
pnpm --filter @agentping/daemon dev &
pnpm --filter @agentping/web-ui dev &

References

CLI Spec: references/cli-reference.md
Design Standards: references/design-standards.md
Component Inventory: references/components.md
Core types: packages/core/src/domain/ping.ts
Parsers: packages/core/src/parsers/index.ts
CLI: packages/adapters/cli/src/index.ts
API: packages/adapters/http-api/src/index.ts
Web UI: packages/adapters/web-ui/src/

Project Status

This is the start of the file. Read the full SKILL.md on GitHub.

Security

Security scanPassed, 95 of 100Pattern checks on the skill's files.
Model reviewPassed

See the full security report

Quality evaluation

Task evaluationWarning, 83 of 100Marginal. 1 run. Evaluated 8 months ago.

See evaluation results

Source

SKILL.md in the repositoryCheckingskills/agentping/SKILL.md

Popularity

Repository stars: 2
7-day trend score: 5

Stars and forks are for the whole GitHub repository, not this skill alone. Refreshed 25 Apr 2026, 6 months ago.

Works with

Any agent vskill installs to: 56 targets in all. These 39 have a page on this site.

Claude Code
Cursor
GitHub Copilot
Windsurf
Codex
Gemini CLI
Cline
Amp
Roo Code
Goose
Continue
Kilo Code
Junie
Trae
OpenHands
Qwen Code
AI Agent
Tabnine Chat
Sourcegraph Cody
Amazon Q
Firebase Genkit
Sweep
Devin
Phind
Mentat
Claude Desktop
Aider
GPT Pilot
Plandex
bolt.new
v0
Replit Agent
Anse
TypingMind
BetterChatGPT
LibreChat
Warp AI
Pieces
Fig AI

Embed badge

[![vskill VERIFIED](https://verified-skill.com/api/v1/skills/lev-os/agents/agentping/badge)](https://verified-skill.com/skills/lev-os/agents/agentping)

Something wrong with this skill or its page? Tell us.