Guide

ChunkyMonkey is a local desktop and CLI workbench for repos that get heavy: game projects, model repos, datasets, Spaces, media folders, notebooks, generated files, and large Git LFS histories.

Install

Download the latest release from ChunkyMonkey Releases.

Requirements:

1. Git on PATH.
2. Git LFS for LFS workflows.
3. GitHub CLI for GitHub login, orgs, repo lists, clone, and create-repo.
4. An editor for Open in editor.

Recommended checks:

git --version
git lfs version
gh auth status

First Use

chunkymonkey status --repo .
chunkymonkey radar --repo . --threshold-mb 75
chunkymonkey plan --repo . --chunk-size 500mb --parts 2
chunkymonkey commit --repo . --chunk-size 500mb --parts 2 --message "Add assets"

Running chunkymonkey with no arguments opens the guided menu. Option 1 is Commit + push chunks.

Desktop Flow

1. Open a repo from the + menu or Repository Management.
2. Stage the files you want, or leave everything unstaged to let ChunkyMonkey inspect all changed files.
3. Use the commit preview before large commits.
4. Commit in chunks by target size or file count.
5. Use Health for asset radar, repair plan, auth checks, and sync checks.
6. Use Review Prep when you want cleaner checkpoints, buckets, branch prep, push, compare, or PR handoff.

Repo Management

Repository Management handles local repo discovery, opening repos, cloning, GitHub repo creation, and editor launch.

Known repos are remembered but not automatically opened. Free mode keeps one active repo tab. Pro enables multi-repo workspace workflows.

Accounts

ChunkyMonkey uses local Git, SSH config, and GitHub CLI.

Git author identity comes from repo-local Git config first, then global config. GitHub org visibility comes from gh auth and SSO/SAML state where required.

The account dropdown near the top bar is for fast account and route checks. It does not rewrite global Git credential settings.

History And Branches

The history graph shows recent commits, refs, authors, dates, and graph lanes.

Branch checkout refuses dirty worktrees. Branch and commit actions include checkout, merge, rebase, rename, delete, cherry-pick, revert, compare, and stash flows.

Review Prep

Review Prep is for turning a messy changed set into a reviewable branch.

It can:

1. Create a checkpoint before risky work.
2. Split changed files into deterministic buckets.
3. Create commits from those buckets.
4. Prepare a review branch.
5. Push or create/open a PR when GitHub CLI, auth, and repo permissions are ready.

Use the generated output as the source of truth before asking someone else to review. If push or PR creation fails, fix the GitHub CLI/auth issue and rerun the relevant step.

Merge Doctor

When Git stops on a merge, rebase, cherry-pick, or revert conflict, ChunkyMonkey opens Merge Doctor in the workbench.

Merge Doctor can:

1. Show conflicted files and the ours/theirs/working versions.
2. Keep ours, keep theirs, or keep both for one file.
3. Open the file in your configured editor.
4. Ask the optional LLM helper for a suggestion.
5. Accept a reviewed full-file suggestion when it has no conflict markers.
6. Abort or finish the active Git operation.

Safety model:

1. A local backup session is created before writing a resolved file.
2. Only the selected file is staged.
3. ChunkyMonkey never creates the final merge commit automatically.
4. Unsafe paths, binary keep-both attempts, oversized suggestions, and suggestions with conflict markers are rejected.
5. If the LLM request fails, deterministic guidance remains available.

Health And Repair

Health includes:

1. Asset Radar for large files missing LFS coverage.
2. Doctor checks for Git, LFS, repo validity, remotes, ignores, and large changed files.
3. Repair plan before apply.
4. ML/media helpers for notebooks, manifests, repro snapshots, and generated junk.

Templates And Profiles

Templates update .gitignore and .gitattributes for game, ML, and media repos.

Profiles are sparse-checkout presets: coder, game, artist, ml, trainer, media, release, and full.

Add-ons

ChunkyMonkey includes built-in repo adapters for Hugging Face and Unity workflows. Settings > Add-ons is for enabling adapters, adding local add-on folders, trusting local backend code, refreshing status, and running add-on actions.

See Add-ons for the developer contract.

Hugging Face Add-on

Included Hugging Face add-on

Hub remotes, local HF auth/tooling, repo actions, Spaces, and full Storage Bucket workflow support.

The built-in Hugging Face adapter is for Hub repos, Spaces, and Storage Buckets.

It can:

1. Detect Hub model, dataset, and Space remotes.
2. Check local HF auth/tooling.
3. List visible models, datasets, and Spaces where local tooling supports it.
4. Inspect repo info and Space runtime state where supported.
5. Clone or create Hub repos through the add-on action flow.
6. Use the Commit panel's Bucket tab to create/check buckets, parse bucket names/URLs/handles, scan large local files, dry-run hf buckets sync, sync, and optionally ignore synced source files.

Bucket sync requires a recent Hugging Face CLI with hf buckets. ChunkyMonkey does not run delete/mirror sync from the UI; it previews first, then syncs without deleting remote extras.

The public Hugging Face Space is a small Hub repo checker: Pwlot/chunkymonkey. The full ChunkyMonkey app remains the desktop/CLI release.

Unity Add-on

Included Unity add-on

Unity project shape, `.meta` files, generated folders, ignore rules, LFS rules, and large asset checks.

The built-in Unity adapter is for Unity project hygiene.

It checks:

1. Unity project shape and editor version.
2. Missing .meta files.
3. Generated folders such as Library/, Temp/, Obj/, Builds/, Logs/, and UserSettings/.
4. Unity .gitignore coverage.
5. Unity .gitattributes and Git LFS coverage.
6. Large untracked assets.

The Unity Editor package is a free editor extension. It opens from Tools > ChunkyMonkey > Repo Doctor, shows repo hygiene inside Unity, can apply ignore/LFS rules, and can open the full ChunkyMonkey desktop app.

Install from Git URL in Unity Package Manager:

https://github.com/pwlot/ChunkyMonkey.git?path=addons/unity/EditorPackage

Settings

Settings control confirmations, repo scan depth, remembered repo count, history range, default editor, update channel, tooltips, dark mode, verbose logs, and optional local LLM helper config. LLM API keys are stored in the OS credential store when available, not in the app state file.

Update channels:

1. Live: latest stable public release.
2. Dev: latest public prerelease.

Pro

Free includes core chunked commit/push, LFS checks, history, basic health, and one active identity/profile.

Pro is a one-time upgrade for multiple identities, per-repo identity memory, fast profile switching, multi-repo workspace, saved presets, and stronger diagnostics/export.

Safety

ChunkyMonkey is local-first:

1. It shells out to local Git.
2. It does not host repositories.
3. It does not send repo contents to a service.
4. It does not run background telemetry.
5. Risky operations can require confirmation.
6. Public bug reports omit raw local paths, remotes, account names, and file lists.
7. Local add-ons that execute backend code require explicit trust and start with common secret environment variables stripped.

Troubleshooting

If a feature says it is unavailable, restart ChunkyMonkey and retry.

If editor detection shows nothing, confirm the editor is installed and available on PATH, or use Browse in Settings.

If GitHub orgs are missing:

gh auth status
gh api user/orgs

Then refresh org access in Repository Management. Private orgs may need SSO/SAML authorization.

If purchase keys are missing, check the checkout success page and email first.

If a local add-on loads but actions do not run, open Settings > Add-ons and confirm it is enabled and trusted.