"The Immutable Foundation for AI Orchestration."

A monorepo for AI-assisted development workflow automation, built around a modular feature architecture with template-based scaffolding, containerized development environments, and agent-driven workflows.

Named after Kuni-no-Tokotachi-no-Kami, the first deity in Japanese mythology to appear and solidify the chaotic, drifting earth into a firm "foundation."

Just as the deity established the ground for all existence, Tokotachi eliminates the chaos of modern AI development environments. It provides a rock-solid, parallel execution platform where multiple AI agents and processes can thrive with absolute stability.

Tokotachi provides a structured foundation for managing multiple development features in a single repository. Each feature is an isolated, self-contained component with its own source code, tests, dependencies, and containerized development environment.

The project is designed to work seamlessly with AI coding agents, enabling a specification → implementation plan → execution pipeline where both humans and AI collaborate through well-defined workflows.

• Feature-based monorepo — isolated modules under features/, each independently buildable and testable
• tt CLI — a development environment orchestrator written in Go
• Template catalog — version-pinned feature templates for reproducible scaffolding
• Agent workflows — structured AI-assisted specification, planning, and implementation processes
• Multi-platform support — Linux, macOS, and Windows with multiple editor/container combinations

tt is built with tt itself.

tokotachi/
├── features/              # All feature implementations
│   ├── tt/                # Development environment orchestrator (Go)
│   └── integration-test/  # Integration test suite (Python)
├── shared/                # Shared resources (libs, schemas, testdata)
├── tests/                 # Project-level test suites
│   └── tt/                # tt integration tests (Go)
├── scripts/               # Build and test automation
│   ├── dist/              # Distribution pipeline (tool/content release)
│   ├── dev/               # Developer environment setup utilities
│   ├── process/           # build.sh, integration_test.sh
│   └── utils/             # Utility scripts
├── prompts/               # AI workflow specifications and rules
│   ├── phases/            # Feature specs and implementation plans
│   └── rules/             # Coding, testing, and planning rules
├── .agent/                # AI agent configuration
│   ├── workflows/         # Workflow definitions
│   └── rules/             # Agent-specific rules
├── bin/                   # Build output (gitignored)
└── work/                  # Git worktrees (gitignored)

The core feature of this repository. tt is a CLI tool that manages feature-level development environments across different OS × Editor × Container combinations.

# 1. Generate a new feature from a template
tt scaffold feature axsh-go-standard
# ... (answer prompts) ...

# 2. Start working — creates worktree, starts container, opens editor
tt open bug-fix-branch myprog

# 3. Done — stops containers and deletes worktree
tt close bug-fix-branch myprog

tt open is a syntax sugar that runs create → up → editor in sequence. If the container is already running, the up step is automatically skipped.

tt close is a syntax sugar that runs down → delete in sequence with a safety confirmation prompt for uncommitted changes.

The editor is resolved in the following priority order:

1. --editor flag (e.g. tt open mybranch tt --editor code)
2. TT_EDITOR environment variable
3. Default configured value in settings (falls back to cursor if unset)

You can dynamically customize editor commands and arguments via the editor.yaml configuration file, supporting custom environments such as code (VSCode), cursor, ag (Antigravity IDE), and claude (Claude Code).

These are the building-block commands that perform a single operation each:

# Worktree management
tt create <branch>                           # Create a branch and worktree
tt delete <branch>                           # Delete worktree and branch
tt delete <branch> --force                   # Force delete even if branch not merged
tt delete <branch> --depth 5 --yes           # Recursive nested worktree deletion

# Container management
tt up <branch> <feature>                     # Start the development container
tt up <branch> <feature> --ssh               # Start with SSH mode
tt up <branch> <feature> --rebuild           # Rebuild the container image
tt down <branch> <feature>                   # Stop and remove the container

# Editor management
tt editor <branch> [feature]                 # Open the editor for a branch
tt editor <branch> [feature] --editor cursor # Specify editor (code|cursor|ag|claude)
tt editor <branch> [feature] --attach        # DevContainer attach to running container

These combine multiple primitive commands into a single operation:

# open = create → up → editor (all-in-one start)
tt open <branch> [feature]                   # Create worktree, start container, and open editor
tt open <branch> [feature] --editor code     # Specify editor to use

# close = down → delete (all-in-one teardown)
tt close <branch> [feature]                  # Stop containers and delete worktree
tt close <branch> [feature] --force          # Force close even if branch not merged
tt close <branch> [feature] --depth 5 --yes  # Recursive close with auto-confirm

# Container interaction
tt status <branch> [feature]                 # Show worktree and container status
tt shell <branch> <feature>                  # Open a shell in the container
tt exec <branch> <feature> -- go test ./...  # Execute a command in the container

# Project management
tt list                                      # List all worktree branches
tt list [branch]                             # List features for a specific branch
tt list --json --path --update --full        # Output options
tt pr <branch> [feature]                     # Create a GitHub Pull Request
tt doctor                                    # Check repository health and config
tt doctor --fix --json                       # Auto-fix with JSON output
tt scaffold [category] [name]                # Generate project structure from templates
tt scaffold --list                           # List available templates
tt scaffold --rollback                       # Rollback last scaffold operation

--verbose      # Show debug logs
--dry-run      # Show planned actions without executing
--report FILE  # Write execution report to Markdown file
--env          # Show environment variables in report

Download the latest release from GitHub Releases.

# Download (replace OS and ARCH as needed: linux/darwin, amd64/arm64)
curl -LO https://github.com/axsh/tokotachi/releases/latest/download/tt_linux_amd64.tar.gz

# Extract
tar xzf tt_linux_amd64.tar.gz

# Move to PATH
sudo mv tt /usr/local/bin/

curl -LO https://github.com/axsh/tokotachi/releases/latest/download/tt_darwin_arm64.tar.gz
tar xzf tt_darwin_arm64.tar.gz
sudo mv tt /usr/local/bin/

Option A: Installer Script (Recommended)

Installs to %LOCALAPPDATA%\Axsh\Tokotachi\bin and configures user PATH. No admin privileges required.

# Clone and install
git clone https://github.com/axsh/tokotachi.git
cd tokotachi
powershell -ExecutionPolicy Bypass -File .\scripts\dist\tool\internal\win\install.ps1

Open a new terminal and verify with tt --help.

To uninstall:

powershell -ExecutionPolicy Bypass -File .\scripts\dist\tool\internal\win\uninstall.ps1

Option B: Manual Install

1. Download tt_windows_amd64.zip from Releases
2. Extract the zip file
3. Move tt.exe to a directory in your PATH

To build from source, you need Go 1.24+, Docker, Git, and Bash (Git Bash on Windows).

To build and install all CLI developer tools defined under the features/ directory:

./scripts/dist/bootstrap-tools.sh

You can build and install a specific tool (such as tt) using individual pipeline scripts:

# Build the binary (outputs to bin/tt)
./scripts/dist/build.sh tt

# Install the built tool to your user PATH
./scripts/dist/install-tools.sh tt

Test automation scripts are located in the scripts/process/ directory.

To compile all modules and run Go package unit tests (excluding the tests/ directory):

./scripts/process/build.sh

• If this script fails (Exit Code != 0), do not proceed to integration tests. Fix all compilation and unit test errors first.

To run integration tests in the tests/ directory (supporting Go test suites and Python test setups):

# Run all integration tests
./scripts/process/integration_test.sh

# Run tests under a specific category (e.g., tests/tt/)
./scripts/process/integration_test.sh --categories "tt"

# Run a specific test case name (passed to Go's -run filter)
./scripts/process/integration_test.sh --categories "tt" --specify "TestEditor_CustomEditorDynamicLaunch"

# Resume from the last failed test category
./scripts/process/integration_test.sh --resume

Release and publishing pipelines are automated via scripts located in the scripts/dist/ directory.

Automates building, packaging, and publishing the tt CLI tool. Note that publishing requires GitHub CLI (gh) credentials.

This runs the full build, packages the binaries, creates a GitHub Release, and publishes update manifests to Scoop/Homebrew:

# A. Release by incrementing patch version (e.g., v2.0.0 -> v2.0.1)
./scripts/dist/tool/release.sh tt

# B. Release with a specific version name
./scripts/dist/tool/release.sh tt v2.1.0

# C. Release by incrementing minor version (e.g., +v0.1.0)
./scripts/dist/tool/release.sh tt +v0.1.0

You can trigger each step of the release pipeline individually for fine-grained control:

./scripts/dist/tool/internal/build.sh tt

./scripts/dist/tool/internal/package.sh tt v2.0.0

./scripts/dist/tool/internal/publish.sh tt v2.0.0

Automates building the templatizer, packaging catalog originals into scaffolds, and pushing updates to the current active branch of the remote repository:

./scripts/dist/content/release.sh

This project uses an AI-assisted development workflow integrated with branch-based release pipelines.

For any code changes (features, tools) or catalog updates (content), create a new feature branch and follow the structured development phases:

  Branch out ──> Specification ──> Implementation Plan ──> Execution ──> Verification

1. Specification — Capture requirements in prompts/phases/ using the create-specification workflow.
2. Implementation Plan — Generate detailed technical plans using the create-implementation-plan workflow.
3. Execution — Implement code, tests, and catalog modifications using the execute-implementation-plan workflow.
4. Verification — Verify changes by running the build-pipeline workflow.

Each phase requires a human review checkpoint before proceeding to the next. AI will not automatically proceed to the next phase without explicit approval.

Once verification is complete, release changes depending on the component type:

The tool release compiles binaries, packages archives, and publishes them directly to GitHub Releases.

• Run ./scripts/dist/tool/release.sh tt to publish the release.
• This script builds the binaries, packages the archives, and uploads them to the distribution channels (such as GitHub Releases).
• Typically run from the main branch or a dedicated release branch after code changes are merged.

Since catalog templates (catalog/scaffolds/, indices, metadata) are stored directly inside the Git repository, content release commits changes to the repository itself:

1. Run Content Release — Execute ./scripts/dist/content/release.sh on your active branch. This automatically builds verification binaries, regenerates the catalog, generates local commits, and pushes them directly to the active remote branch.
2. Create Pull Request — Create a Pull Request (PR) from your feature branch to the main branch on GitHub.
3. Merge and Complete — Once the PR is merged, the release is complete. The new catalog templates become immediately active and resolvable by tt clients.

New features are generated from templates using the scaffold command and placed under features/:

tt scaffold [category] [name]

• Coding Rules
• Testing Rules
• Planning Rules
• Vibe Coding Standard

This project is licensed under the GPLv3 License.