Merge pull request #21 from osodevops/codex/bundled-keito-skill

Bundle Keito agent skill with CLI

Author: sionsmith

CHANGELOG.md

@@ -5,6 +5,22 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.1.7] - 2026-06-16
+
+### Added
+
+- Bundle the `keito-time-track` agent skill with the CLI so `keito skill install` no longer depends on an external skill repository by default.
+- Add a gstack-style `./setup` entrypoint for source-checkout installs with Claude Code and Codex target selection.
+- Add `keito skill team-init optional|required` to write repo-level agent guidance and `.keito/config.example.yml`.
+- Add packaged lifecycle hook tests that exercise the bundled skill with a fake Keito CLI.
+- Add AI-native services positioning notes for agent billing, project attribution, and client profitability.
+
+### Changed
+
+- Keep the audit-first external skill install path available through `--source` and `--skip-skills-add`.
+- Document the bundled skill install, repo setup workflow, and release positioning in README and the agent guide.
+- Accept `calendar` and `desktop` as time entry source values alongside `web`, `cli`, `api`, and `agent`.
+
 ## [0.1.6] - 2026-05-12
 
 ### Changed

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "keito-cli"
-version = "0.1.6"
+version = "0.1.7"
 edition = "2021"
 description = "AI agent time tracking CLI for Keito: capture billable human and agent work for client billing, agency projects, and AI-native services"
 license = "MIT"

Cargo.toml

@@ -8,6 +8,10 @@ Track billable human and AI agent work in [Keito](https://keito.ai) from the ter
 
 Keito is built for teams selling outcomes with people and AI agents. The CLI helps make that work visible for client billing, project profitability, time tracking, and invoice review.
 
+Keito is billing and profitability infrastructure for AI-native services teams:
+agent work is recorded against the same clients, projects, tasks, and invoices
+as human work, with metadata for margin and audit analysis.
+
 <p align="center">
   <img src="recordings/time-start-stop-optimised.gif" alt="keito demo" width="720" />
 </p>
@@ -110,14 +114,137 @@ Exit codes tell you exactly what happened — no need to parse error messages. S
 
 ## Agent Skill
 
-The Keito Agent Skill is installed from the GitHub skill repo, not from an npm package:
+The Keito Agent Skill ships with this CLI. It brings Keito to the places where
+agents already work by installing lifecycle hooks for Claude Code and OpenAI
+Codex CLI, then recording one `source=agent` time entry when a tracked coding
+session ends.
+
+### Requirements
+
+- Claude Code and/or Codex CLI
+- Git, Bash, and `jq`
+- Keito credentials via `keito auth login` or `KEITO_API_KEY` +
+  `KEITO_ACCOUNT_ID`
+- macOS/Linux: `./setup` can install the CLI through Homebrew or release
+  tarballs if `keito` is not already on `PATH`
+- Windows: install the binary from
+  [Releases](https://github.com/osodevops/keito-cli/releases) first, then run
+  the skill commands from Git Bash or WSL where `bash` and `jq` are available
+
+### Step 1: Install on your machine
+
+Open Claude Code or Codex and paste this. The agent can run the same
+source-checkout flow that gstack documents:
+
+```sh
+git clone --single-branch --depth 1 https://github.com/osodevops/keito-cli.git ~/.keito/keito-cli
+cd ~/.keito/keito-cli
+./setup
+```
+
+`./setup` installs the CLI if needed, installs the bundled `keito-time-track`
+skill, and configures hooks for Claude Code, Codex, or both. In an interactive
+terminal it asks which host to configure. In non-interactive runs it defaults
+to both.
+
+Target one host explicitly when needed:
+
+```sh
+~/.keito/keito-cli/setup --host claude
+~/.keito/keito-cli/setup --host codex
+~/.keito/keito-cli/setup --host both
+```
+
+If the CLI is already installed, this equivalent command uses the bundled skill
+without the source checkout:
 
 ```sh
-keito auth login
 keito skill install
 ```
 
-`keito skill install` uses `npx` only to run the open skills installer. The installer package is pinned to `skills@1.5.6` by default and can be overridden intentionally with `KEITO_SKILLS_PACKAGE`.
+Choose one target when needed:
+
+```sh
+keito skill install --agent claude-code
+keito skill install --agent codex
+```
+
+Check readiness:
+
+```sh
+keito skill doctor
+keito skill status --json
+```
+
+### Step 2: Configure each client repo
+
+From each client repository, invoke the skill once to map that worktree to a
+Keito client, project, and task:
+
+```text
+/track-time-keito
+```
+
+This writes `.keito/config.yml`, which is intentionally repo-local and should
+not be committed.
+
+### Team Mode
+
+For shared repos, use the same model as gstack team mode: the skill remains
+globally installed, and the repository commits only agent guidance plus an
+example config.
+
+From inside the shared repo:
+
+```sh
+~/.keito/keito-cli/setup --team optional
+git add AGENTS.md CLAUDE.md .gitignore .keito/config.example.yml
+git commit -m "add Keito tracking guidance for agent work"
+```
+
+Use `required` instead of `optional` when agents must stop before billable
+coding work until `/track-time-keito` has configured the repo:
+
+```sh
+~/.keito/keito-cli/setup --team required
+```
+
+If the CLI is already installed and the global skill is already configured, you
+can run only the repo bootstrap:
+
+```sh
+keito skill team-init optional
+keito skill team-init required
+```
+
+`team-init` writes `AGENTS.md`, `CLAUDE.md`, `.gitignore`, and
+`.keito/config.example.yml`. It does not vendor the skill into the repo. Do not
+commit `.keito/config.yml`; that file contains the local project/task mapping
+created by `/track-time-keito`.
+
+### How It Works
+
+- `./setup` is the gstack-style source-checkout installer. It keeps a stable
+  checkout at `~/.keito/keito-cli`, installs the CLI if needed, then calls
+  `keito skill install --source bundled`.
+- `keito skill install` materializes the bundled `keito-time-track` skill and
+  copies it into agent home directories:
+  `~/.claude/skills/keito-time-track` for Claude Code and
+  `~/.codex/skills/keito-time-track` for Codex.
+- The hook installers merge lifecycle hooks into `~/.claude/settings.json` and
+  `~/.codex/hooks.json` using `jq`.
+- `/track-time-keito` verifies auth, asks for the Keito client/project/task for
+  the current repo, and writes `.keito/config.yml`.
+- On agent session start, the hook records local session state. On session end,
+  the hook logs one Keito time entry with `source=agent` and metadata such as
+  repo path, branch, commit, and agent type.
+
+Audit-first external install remains available:
+
+```sh
+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
+```
 
 ## Features
 

README.md

@@ -28,6 +28,47 @@ keito auth status --json
 
 Exit code `0` = ready. Exit code `1` = fix credentials.
 
+## Skill Installation
+
+Install the packaged Keito skill into Claude Code and Codex:
+
+```sh
+keito skill install
+```
+
+Install one host only when needed:
+
+```sh
+keito skill install --agent claude-code
+keito skill install --agent codex
+```
+
+For source-checkout installs, use the gstack-style setup entrypoint:
+
+```sh
+git clone --single-branch --depth 1 https://github.com/osodevops/keito-cli.git ~/.keito/keito-cli
+cd ~/.keito/keito-cli
+./setup
+```
+
+From each client repository, invoke the skill once:
+
+```text
+/track-time-keito
+```
+
+This writes `.keito/config.yml` with the selected Keito client, project, and
+task IDs. Do not commit that file. For shared repositories, run
+`keito skill team-init optional` or `keito skill team-init required` to add
+agent guidance plus `.keito/config.example.yml`.
+
+Check readiness:
+
+```sh
+keito skill doctor
+keito skill status --json
+```
+
 ## Discovery
 
 ### List Projects

docs/agent-guide.md

@@ -0,0 +1,97 @@
+# Keito Positioning: AI-Native Services
+
+Keito should be positioned as billing and profitability infrastructure for
+AI-native services companies.
+
+## Why Now
+
+YC's Summer 2026 Request for Startups explicitly calls for **AI-Native Service
+Companies**: companies that do not sell software, but sell the completed
+service. YC also calls for **Software for Agents**, arguing that agents need
+machine-readable APIs, MCPs, CLIs, and documentation so they can use tools
+programmatically without a human in the loop.
+
+Sources:
+- https://www.ycombinator.com/rfs
+- https://github.com/garrytan/gstack
+
+The category implication is direct: if agents are doing client work, the
+software around services businesses has to become agent-native too. Billing,
+time tracking, project mapping, approvals, and profitability reporting cannot
+remain browser-only workflows for humans.
+
+## Category Frame
+
+Keito is not LLM cost observability.
+
+LLM observability answers:
+- Which model ran?
+- How many tokens did it use?
+- What did the inference cost?
+- Was latency or quality acceptable?
+
+Keito answers:
+- Which client and project did the agent work for?
+- What task was delivered?
+- What time or effort should flow into billing?
+- What did that work cost internally?
+- What margin did the client, project, workflow, or agent generate?
+
+Lightspeed's investment note on Paid frames the same gap as missing economic
+infrastructure for AI agents: traditional SaaS pricing breaks when agents are
+autonomous digital workers, and the missing capabilities are value proof,
+custom pricing, outcome and hybrid models, cost tracking, and customer
+profitability dashboards.
+
+Source:
+- https://lsvp.com/stories/the-ai-agent-economy-has-a-19-trillion-problem-our-investment-in-paid/
+
+## Buyer
+
+Primary buyer:
+- AI-native agencies and consultancies
+- Professional-services teams using coding, research, support, finance, or
+  operations agents
+- YC-style startups replacing outsourced services with agent-run delivery
+
+The buyer wants software-margin economics without losing service-business
+controls: client attribution, auditability, utilization, approval, invoices,
+and profitability.
+
+## Messaging
+
+Use this compact positioning:
+
+> Keito is the billing and profitability layer for AI-native services teams.
+> Agents log work against clients, projects, and tasks the same way humans do,
+> so firms can invoice accurately, prove value, and see margin by customer and
+> workflow.
+
+Supporting claims:
+- "Bring Keito to where agents work": ship a CLI plus Codex and Claude Code
+  skills, not a dashboard-only workflow.
+- "Track billable work, not just token spend": connect agent activity to
+  projects, invoices, and margin.
+- "One worktree, one client/project/task mapping": repo-local setup keeps
+  agent time from leaking across clients.
+- "Best-effort hooks, deterministic CLI": agent sessions should never fail
+  because billing telemetry failed, but failures must be logged and recoverable.
+
+## Product Implications For The CLI
+
+The CLI should prioritize:
+- Bundled agent skills for Codex and Claude Code.
+- A gstack-style install flow: install globally, then bootstrap each repo.
+- Deterministic `--json` commands and stable exit codes.
+- `source=agent` entries with metadata for session ID, agent type, skill, git
+  branch, git revision, duration, and draft status.
+- Repo-local `.keito/config.yml` selected by a wizard and excluded from git.
+- `keito skill status` and `keito skill doctor` for agent-readable readiness.
+
+MindStudio's monetization guide makes the margin reason explicit: successful
+AI-agent businesses need disciplined cost tracking and 60-75% gross margins;
+cost creep at the interaction level can erase margin. Keito should connect
+that cost discipline to the professional-services billing system.
+
+Source:
+- https://www.mindstudio.ai/blog/build-monetize-ai-agents-business