Tool Installation Guide

One-time setup steps for the Tom CLI tools: buildkit, testkit, issuekit, and navigation helpers.

---

Table of Contents

1. Binary Installation - Pre-built Binaries - Building from Source 2. PATH Configuration 3. Shell Navigation 4. Shell Completion 5. GitHub Token (issuekit) 6. Workspace Configuration (issuekit)

---

Binary Installation

Pre-built Binaries

Pre-built binaries are available in tom_binaries/tom/<platform>/:

Platform	Directory
macOS ARM64	darwin-arm64
macOS x64	darwin-x64
Linux x64	linux-x64
Linux ARM64	linux-arm64

The binaries are committed to the tom_binaries repository and automatically updated when tools are recompiled.

Building from Source

To compile all binaries from source, run the bootstrap script:

cd tom_ai/basics/tom_build_kit
./bootstrap_binaries.sh

The script: 1. Auto-detects your platform (or accepts a platform argument) 2. Generates version metadata 3. Compiles all tools to tom_binaries/tom/<platform>/

For cross-compilation:

./bootstrap_binaries.sh linux-x64

Tools compiled: - buildkit — Main build orchestration tool - versioner, compiler, cleanup, runner, dependencies, bumpversion, buildsorter, publisher - findproject — Project path resolver - Git tools: gitbranch, gitcheckout, gitclean, gitcommit, gitcompare, gitmerge, gitprune, gitpull, gitrebase, gitreset, gitsquash, gitstash, gitstatus, gitsync, gittag, gitunstash

Other tools (separate projects): - testkit — From tom_test_kit - issuekit — From tom_issue_kit

---

PATH Configuration

Add the binary directory to your shell's PATH. In ~/.zshrc (or ~/.bashrc):

# Tom CLI tools
export PATH="$HOME/repos/tom_agent_container/tom_binaries/tom/darwin-arm64:$PATH"

Replace darwin-arm64 with your platform and adjust the path to match your workspace location.

Verify installation:

buildkit --version
testkit --version
issuekit --version

---

Shell Navigation

The findproject command resolves project paths but cannot change the shell's working directory (child processes cannot modify parent state). Use a shell function wrapper instead.

Add to ~/.zshrc:

# Go to project directory (wraps findproject binary)
# Usage: goto <project-name|project-id|folder>
goto() {
  local d
  d="$(findproject "$@" 2>/dev/null)"
  if [[ -n "$d" && -d "$d" ]]; then
    cd "$d"
  else
    # Run findproject again for stderr output (error messages, help)
    findproject "$@"
    return 1
  fi
}

Usage:

goto tom_build_kit      # Navigate to tom_build_kit project
goto buildkit           # Navigate by project ID
goto "Tom Build Kit"    # Navigate by project name

How it works: 1. findproject walks up from the current directory, scanning at each repository or workspace "anchor" it recognises 2. At each anchor, it searches for projects matching by folder name, project ID, or project name 3. Outputs the absolute path to stdout (or error messages to stderr) 4. The goto function captures the path and uses the shell builtin cd to navigate

---

Shell Completion

Shell completion scripts can be generated for bash, zsh, and fish. Run:

buildkit :completion --shell zsh > ~/.zsh/completions/_buildkit
testkit :completion --shell zsh > ~/.zsh/completions/_testkit
issuekit :completion --shell zsh > ~/.zsh/completions/_issuekit

Ensure your completion directory is in fpath:

# In ~/.zshrc
fpath=(~/.zsh/completions $fpath)
autoload -Uz compinit && compinit

For bash:

buildkit :completion --shell bash >> ~/.bash_completion

---

GitHub Token (issuekit)

issuekit requires a GitHub Personal Access Token (PAT) with repo scope for reading/writing issues.

Token resolution order: 1. gh auth — If GitHub CLI is installed and authenticated 2. GITHUB_TOKEN environment variable 3. Token file at ~/.tom/github_token (first line, trimmed)

Option 1: GitHub CLI (Recommended)

# Install GitHub CLI
brew install gh

# Authenticate
gh auth login

The token is managed automatically and refreshed as needed.

Option 2: Environment Variable

Add to ~/.zshrc:

export GITHUB_TOKEN="ghp_your_token_here"

Option 3: Token File

echo "ghp_your_token_here" > ~/.tom/github_token
chmod 600 ~/.tom/github_token

Required token scopes: - repo — Full control of private repositories (for creating/updating issues)

---

Workspace Configuration (issuekit)

issuekit resolves the GitHub repositories it reads and writes from its own workspace configuration. That configuration is the tool's, so it is documented with the tool — see tom_ai/devops/tom_issue_kit/ and issuekit --help. This guide covers installation and PATH only.

---

Quick Reference

Task	Command
Navigate to project	goto <project>
List issues	issuekit :list
Run tests	testkit :test
Create baseline	testkit :baseline
Build project	buildkit :build
Show help	<tool> --help

---

Troubleshooting

Command not found

Verify PATH includes the binary directory:

echo $PATH | tr ':' '\n' | grep tom

goto doesn't work

1. Verify findproject is in PATH: which findproject 2. Verify the shell function is defined: type goto 3. Source your shell config: source ~/.zshrc

issuekit can't connect to GitHub

1. Check token: issuekit :auth-status (if available) or test with gh auth status 2. Verify the workspace carries an issue-tracking configuration (issuekit --help) 3. Ensure token has repo scope

testkit can't find tests

Run from the project root (directory with pubspec.yaml):

cd /path/to/project
testkit :test