{"id":30858663,"url":"https://github.com/carlsverre/kosho","last_synced_at":"2025-09-07T14:16:29.433Z","repository":{"id":304601146,"uuid":"1019254040","full_name":"carlsverre/kosho","owner":"carlsverre","description":"A CLI tool for managing git worktrees to enable concurrent development environments.","archived":false,"fork":false,"pushed_at":"2025-09-04T20:12:05.000Z","size":97,"stargazers_count":22,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-09-04T21:27:21.299Z","etag":null,"topics":["agent","ai","claude","claude-code","git","worktree"],"latest_commit_sha":null,"homepage":"https://kosho.ai","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/carlsverre.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-07-14T03:45:44.000Z","updated_at":"2025-09-04T20:10:55.000Z","dependencies_parsed_at":"2025-07-14T07:39:39.119Z","dependency_job_id":"edb2e724-6378-45fb-8155-8c53c9d2be79","html_url":"https://github.com/carlsverre/kosho","commit_stats":null,"previous_names":["carlsverre/kosho"],"tags_count":3,"template":false,"template_full_name":null,"purl":"pkg:github/carlsverre/kosho","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlsverre%2Fkosho","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlsverre%2Fkosho/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlsverre%2Fkosho/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlsverre%2Fkosho/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/carlsverre","download_url":"https://codeload.github.com/carlsverre/kosho/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/carlsverre%2Fkosho/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273748693,"owners_count":25160885,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-05T02:00:09.113Z","response_time":402,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","ai","claude","claude-code","git","worktree"],"created_at":"2025-09-07T14:16:26.204Z","updated_at":"2025-09-07T14:16:29.397Z","avatar_url":"https://github.com/carlsverre.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n  \u003ch1 align=\"center\"\u003eKōshō\u003c/h1\u003e\n  \u003cp align=\"center\"\u003e\u003cem\u003eA loyal assistant, trained for quiet efficiency.\u003c/em\u003e\u003c/p\u003e\n\u003c/p\u003e\n\n---\n\n**Kosho** creates and manages [git worktree]s in `.kosho/` directories, making it easy to work on multiple branches simultaneously without the overhead of cloning repositories or switching contexts.\n\n```bash\ngo install github.com/carlsverre/kosho\n```\n\n## Why Use Kosho?\n\nKosho is well-suited for **running multiple concurrent AI coding agents** like Claude Code, each working on different features or branches in separate workspaces:\n\n- **🤖 Multiple AI Agents**: Run Claude Code (or other AI tools) in separate worktrees simultaneously\n- **⚡ Reduced Context Switching**: Work on multiple branches/features at once without git checkout delays\n- **🔒 Workspace Isolation**: Each agent operates in its own [git worktree] with independent working state\n- **🚀 More Efficient Than Cloning**: Worktrees share the same `.git` directory - no duplicate repositories\n- **📋 Easy Coordination**: Use `kosho list` to see what each agent is working on\n- **🧹 Easy Cleanup**: Remove completed work environments without affecting your main repository\n\n**Example workflow using Claude Code:**\n\n```bash\n# Start Claude Code on feature branch\nkosho open feature-auth -b feature/user-auth -- claude\n\n# Start another agent on bug fixes in a separate shell\nkosho open bugfix-session -- claude\n\n# Check what each agent is working on\nkosho list\n\n# Merge completed work back to main branch\nkosho merge feature-auth -- --squash\nkosho merge bugfix-session --remove\n\n# Clean up merged worktrees\nkosho remove feature-auth\n```\n\n## Basic Usage\n\n1. **Create and open a worktree**:\n\n   ```bash\n   kosho open my-feature\n   ```\n\n   This creates a new worktree at `.kosho/my-feature`, checks out or creates the branch called `my-feature`, and opens a shell session.\n\n2. **Run a command in a worktree instead of opening a shell**:\n\n   ```bash\n   kosho open my-feature -- claude\n   ```\n\n   Start a Claude Code agent in the new worktree.\n\n3. **List all worktrees**:\n\n   ```bash\n   kosho list\n   ```\n\n4. **Remove a worktree**:\n\n   ```bash\n   kosho remove my-feature\n   ```\n\n## Commands\n\n### `kosho open [flags] NAME [commitish] [-- command...]`\n\nCreates or opens a worktree. If the worktree doesn't exist, it will be created.\n\n**Arguments:**\n\n- `NAME` (required): Name of the worktree\n- `commitish` (optional): Git commit-ish to base the worktree on\n\n**Flags:**\n\n- `-b, --branch \u003cname\u003e`: Create a new branch\n\n**Examples:**\n\n```bash\n# Create worktree from current HEAD\nkosho open bugfix\n\n# Create worktree with new branch\nkosho open feature-work -b feature/awesome-feature\n\n# Create worktree from specific commit\nkosho open hotfix v1.2.3\n\n# Run command instead of opening shell\nkosho open testing -- npm test\n```\n\n### `kosho list`\n\nLists all kosho worktrees with their status and current git reference.\n\n**Output:**\n\n```\nNAME        UPSTREAM  REF     STATUS\nbugfix      main      bugfix  ahead 1\nhotfix      main      bug/1   ahead 2 (dirty)\nsecurity    release   sec/1   ahead 1\n```\n\n### `kosho remove [flags] NAME`\n\nRemoves a worktree and cleans up git references.\n\n**Flags:**\n\n- `-f, --force`: Force removal even if worktree has uncommitted changes\n\n**Examples:**\n\n```bash\n# Remove clean worktree\nkosho remove my-feature\n\n# Force remove dirty worktree\nkosho remove my-feature --force\n```\n\n### `kosho merge [worktree] [-- git-merge-args...]`\n\nMerges a worktree branch into the current branch of the main repository.\n\n**Requirements:**\n\n- Worktree must be clean (no uncommitted changes)\n- Current branch must be an ancestor of the worktree branch\n\n**Examples:**\n\n```bash\n# Standard merge\nkosho merge feature-auth\n\n# Squash merge\nkosho merge feature-auth -- --squash\n\n# No-fast-forward merge with message\nkosho merge feature-auth -- --no-ff -m \"Add authentication feature\"\n```\n\n### `kosho prune`\n\nCleans up any dangling worktree references using `git worktree prune`.\n\n## Hooks\n\nKosho supports hooks that run at specific points during worktree operations. Hooks are executable scripts stored in `.kosho/hooks/` and receive environment variables with context about the operation.\n\n### Available Hooks\n\n- **`create`**: Runs after a new worktree is created, before opening it\n- **`open`**: Runs before opening an existing worktree\n- **`merge`**: Runs during merge operations, before validation\n- **`remove`**: Runs before removing a worktree, before validation\n\n### Enabling Hooks\n\nKosho automatically creates sample hook files (`.sample` extension) in `.kosho/hooks/`. To enable a hook:\n\n```bash\n# Enable the create hook\nmv .kosho/hooks/create.sample .kosho/hooks/create\n```\n\n### Environment Variables\n\nHooks receive these environment variables:\n\n- `$KOSHO_HOOK`: The hook type (`create`, `open`, `merge`, `remove`)\n- `$KOSHO_WORKTREE`: Name of the worktree being operated on\n- `$KOSHO_REPO`: Path to the repository root\n- `$PWD` / `$KOSHO_WORKTREE_PATH`: Full path to the worktree directory (the hook is also run within the worktree directory)\n\n**Example create hook (`.kosho/hooks/create`):**\n\n```bash\n#!/bin/sh\necho \"Setting up new worktree: $KOSHO_WORKTREE\"\necho \"Worktree path: $KOSHO_WORKTREE_PATH\"\necho \"Repository root: $KOSHO_REPO\"\n\n# Copy environment file from repo root to worktree\ncp \"$KOSHO_REPO/.env.example\" \"$KOSHO_WORKTREE_PATH/.env\"\n\n# Install dependencies when creating a new worktree\nnpm install\n```\n\n## How It Works\n\nKosho manages [git worktree]s in a `.kosho/` directory at your repository root:\n\n```\nyour-repo/\n├── .git/\n├── .kosho/               # Kosho root directory\n│   ├── .gitignore        # Kosho specific gitignore\n│   ├── worktrees/\n│   │   ├── feature-a/    # Worktree for feature-a\n│   │   ├── bugfix/       # Worktree for bugfix\n│   │   └── experiment/   # Worktree for experiment\n│   └── hooks/\n│       └── create        # Hook script which runs when creating a worktree\n├── src/\n└── README.md\n```\n\nEach worktree is a complete working directory that shares the same git history but can have different branches checked out and different working states.\n\n## Shell Completion\n\nKosho supports tab completion for bash, zsh, fish, and PowerShell. To set up completion for your shell:\n\n```bash\nkosho completion \u003cshell\u003e --help\n```\n\nThis command outputs detailed setup instructions specific to your shell.\n\n## Tips\n\n- The `.kosho` directory is automatically added to your `.gitignore`\n- Each worktree maintains its own working state and uncommitted changes\n- Use `kosho list` to see the status of all your worktrees at a glance\n- Use `kosho prune` periodically to clean up any orphaned references\n\n[git worktree]: https://git-scm.com/docs/git-worktree\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlsverre%2Fkosho","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcarlsverre%2Fkosho","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcarlsverre%2Fkosho/lists"}