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.

What It Does

The Agent Skill can:

Install Codex and Claude Code hooks for local session tracking.
Use the Keito CLI for authentication and API writes.
Configure each repository with its own Keito company, client, project, and task.
Log completed local agent sessions as Keito time entries.
Store session metadata such as agent type, git branch, git revision, and session duration.
Skip repositories that have not been configured.

How It Works

The skill runs locally through Codex and Claude Code hooks. When an agent session ends, the hook searches upward from the active working directory for .keito/config.yml. If that file exists and tracking is enabled, the hook uses the Keito CLI to write the session duration and metadata to the configured project and task.

The skill does not store API keys in the repository. Credentials stay in the Keito CLI config file or in KEITO_API_KEY and KEITO_ACCOUNT_ID.

Connect The Agent Skill

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 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:

Verifies jq and the Keito CLI are available.
Verifies the CLI is authenticated.
Lists clients the credential can access.
Lists projects for the selected client.
Lets permitted users create a client or project from the CLI when needed.
Selects a task.
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, 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

Agent	Skill files	Hook 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

Disconnect Or Remove The Agent Skill

To stop tracking one repository, edit or remove that repository’s .keito/config.yml. The hooks skip repositories without an enabled Keito config.

To stop tracking for a single agent, remove the Keito hook entry from that agent’s hook file:

Agent	Hook config
Codex	`~/.codex/hooks.json`
Claude Code	`~/.claude/settings.json`

To remove the installed skill files, delete the Keito skill directories listed in File Locations. Then run:

keito skill doctor

Use the doctor output to confirm the hooks and skill files are no longer active. Existing time entries created by the skill remain in Keito.

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.