Keito Agent Skill

The Keito Agent Skill lets Codex and Claude Code log local coding sessions to Keito automatically. The skill installs hooks for your agent, uses the Keito CLI for authentication and API writes, and stores project mapping per repository.

Install

Recommended path:

brew install osodevops/tap/keito
keito auth login
keito skill install

keito skill install installs the skill from the GitHub skill repo, configures Codex and Claude Code hooks, and then reports readiness. The skill itself is not published to npm; npx is only used to run the pinned open skills installer package.

Audit-first path:

npx --yes skills@1.5.6 add osodevops/keito-skill -g -a codex -a claude-code -s keito-time-track -y --copy
keito skill install --skip-skills-add

If the skill is installed before the CLI, run /track-time-keito from Codex or Claude Code. The skill checks for keito, installs it when possible, and then asks you to authenticate with keito auth login before setup continues.

First Repository Setup

Run the wizard from the repository that should be tracked:

cd ~/work/acme-project
# In Codex or Claude Code:
/track-time-keito

The wizard:

  1. Verifies jq and the Keito CLI are available.
  2. Verifies the CLI is authenticated.
  3. Lists clients the credential can access.
  4. Lists projects for the selected client.
  5. Lets permitted users create a client or project from the CLI when needed.
  6. Selects a task.
  7. Writes .keito/config.yml in the current repository only.

Repository Config

Example .keito/config.yml:

version: 1
workspace_id: co_example
client_id: cli_example
client_name: "Example Client"
project_id: prj_example
project_name: "Example Project"
task_id: tsk_development
task_name: "Development"
agent_tracking:
  enabled: true
  source: agent
  draft: true
  min_duration_seconds: 60
  max_duration_seconds: 28800
  redact_notes: false
metadata:
  integration: keito_skill
  cost_centre: engineering

Each repository needs its own config. The hook starts from the active working directory, searches upward for .keito/config.yml, and uses only that repository’s mapping. A session in client-a-api cannot inherit the mapping from client-b-web unless that config is copied there manually.

What Gets Logged

When an agent session ends, the hook creates a Keito time entry with:

  • source=agent
  • the configured project and task IDs
  • elapsed session duration, capped by max_duration_seconds
  • notes from the agent payload or transcript
  • metadata including integration=keito_skill, session ID, agent type, git branch, git revision, and duration details

Set agent_tracking.redact_notes: true if notes should be generic instead of transcript-derived.

File Locations

AgentSkill filesHook config
Codex~/.agents/skills/keito-time-track and hook runtime in ~/.codex/skills/keito-time-track~/.codex/hooks.json
Claude Code~/.claude/skills/keito-time-track~/.claude/settings.json

Verify

keito skill doctor
keito --json skill status

After the next agent session, check Keito’s Timesheet week view or run:

keito --json time list --today

Security

  • The skill does not store API keys in repository config.
  • Credentials stay in the Keito CLI config file or in KEITO_API_KEY and KEITO_ACCOUNT_ID.
  • API access is scoped by the authenticated company and the user’s Keito permissions.
  • The repository config stores IDs for the selected company, client, project, and task.
  • Hooks skip unconfigured repositories.
  • Failed writes preserve local session state so the session can be retried instead of silently dropped.
  • The public install path pins the npm-hosted installer package as skills@1.5.6.
  • GitHub Actions in the skill repo are pinned to commit SHAs and run with read-only repository permissions.

See Also