ClashGO

command module

v0.6.0-beta Latest Latest Go to latest Published: Sep 28, 2026 License: MIT Imports: 21 Imported by: 0

Details

Valid go.mod file
Redistributable license
Tagged version
Stable version
Learn more about best practices

Repository

github.com/Ducky705/ClashGO

Links

Open Source Insights

README ¶

ClashGO ⚔️

This is ClashGO, a super lightweight Clash of Clans bot written in Go.

I basically vibe-coded this in like 3 days because I wanted a bot that actually worked on my Mac (Apple Silicon). It's built from scratch using Go and OpenCV.

⚠️ WARNING: It's Buggy

Look, I made this fast. It's rough around the edges, probably has bugs, and might crash. Use it at your own risk.

🚀 Why it's cool

Mac Native: Works great on Apple Silicon.
Fast: Uses a persistent ADB connection, so screen captures and taps are instant.
Lightweight: Just a single binary, with a recent perf audit cutting battle-state CPU ~10–20% and transient RSS ~10–20 MB. See docs/PERFORMANCE.md for the per-change breakdown and how to verify on your machine.
Customizable strategies: Drop a YAML strategy + matching formula.json (per-unit deploy coords) into assets/strategies/ and the bot deploys each unit where you want. See assets/strategies/auto_edrag_rush.yaml + assets/strategies/auto_edrag_rush_formula.json for an end-to-end example (Balloon + EDrag + Rage + Ice).
Per-corner formula workflow: target_edge: "Random" (the default in auto_edrag_rush.yaml) picks a random corner per attack. cmd/design_attack -live -corner BR|BL|TR|TL authors the per-corner deploy coords; per-corner overrides in formula.corner_overrides[<CORNER>] are used as-authored (the mirror is only a fallback). See docs/formula-authoring.md for the full walkthrough.
Self-healing boot sequence: the bot auto-dismisses the post-boot splash chain ("ТАР!" tap-to-continue → castle logo → news splash) instead of force-restarting in a loop, so unattended runs survive game relaunches.
Unattended-run resilience: if the emulator dies mid-session the bot escalates through transport reconnect → adb-server reset → BlueStacks relaunch instead of spinning; a bad frame or missing asset can't crash the process (panic guards + nil-template fallback); and tools/run_bot_keepalive.sh respawns the bot ~10s after any exit so it keeps farming unattended.
Text-based observability: ./tools/observe.sh captures the emulator screen, classifies it with the bot's real vision layer, and OCRs the on-screen text — a terminal-only "eye view" for debugging without a GUI. See docs/OBSERVABILITY.md.
Replayable attacks: make attack-record records a deploy you perform on the emulator; make attack-replay re-fires that JSON on the device with classification + extras. Useful for sharing working attacks without re-engineering.
- In-app updater (auto-pop): New releases ship through GitHub Releases. When a version is published, ClashGO pops up the update window on its own (no click needed) offering one-click Update & Restart: it downloads the zip, verifies the SHA256 against latest.json, swaps the running app in place, and relaunches. No new servers, no manual checks. "Later" silences it for the session; "Skip version" silences it permanently.

🛠️ How to use

Emulator: Set your emulator (like BlueStacks) to 860x732 resolution and 160 DPI.
Config: Point config.json to your ADB device.
Run:
- CLI: make build-cli && ./build/bin/bot_cli
- GUI: make build-gui and run build/bin/ClashGO.app

💾 Resource usage (estimates)

All numbers below are principled estimates from code analysis (frame sizing, mat pool, template cache, capture-loop cadence), not live measurements. They assume an Apple Silicon Mac, BlueStacks at 860×732 / 160 DPI, and the bot running at the configured capture rate. The recipe in docs/PERFORMANCE.md validates them on your machine.

Frame math (860×732, RGB):

Full capture frame: 860 × 732 × 3 ≈ 1.80 MB
Half-size frame (Live View JPEG encode): 430 × 366 × 3 ≈ 0.47 MB

Scenario	ClashGO (Go) RSS	ClashGO CPU¹	+ BlueStacks RSS²	Combined RSS (est.)
Idle / UI only (1 FPS capture)	~60–90 MB	~1–3% (1 core)	~800 MB–1.2 GB	~0.9–1.3 GB
Active battle @ 15 FPS	~90–140 MB	~15–25% (1 core)	~1.0–1.5 GB	~1.1–1.7 GB

¹ CPU is single-core; the bot is largely single-threaded per capture frame (classify + template match + tap). Higher FPS = proportionally more CPU. At 15 FPS the per-frame vision work (~7–15 ms) consumes ~15–25% of one core. The bot also reports cpu_time_sec — absolute CPU time since process start — which is the device-independent metric: it means the same on an M1 or an M3 Max, so you can compare efficiency across machines without normalizing by core count. The "% CPU" shown in the UI is derived by multiplying the per-core fraction (cpu_cores) by the host's logical core count; treat that number as host-relative only. ² BlueStacks footprint is driven by the emulator + Android guest, not the bot. It scales with emulator window size / DPI and the guest's own memory pressure, not with ClashGO's FPS.

Where the bot's RAM goes:

Capture + working Mats (mat pool): ~2–4 MB retained (serial capture keeps only 1–2 mats per size alive).
ScaledTemplateCache (6 classifier rules × several scales): ~1–3 MB.
Live View base64 frame buffer (lastFrame): a few hundred KB.
Wails/WebKit GUI harness: the bulk of the idle ~60–90 MB is the embedded browser, not the Go bot logic.

ClashGO itself is tiny; the dominant memory cost when running is almost always BlueStacks, not the bot.

🚢 Releasing a new version

Updates are powered by GitHub Releases — no extra infrastructure.

Bump productVersion in wails.json (e.g. 0.3.0-beta).
Commit + push, then tag it:
```
git tag v0.3.0-beta && git push origin v0.3.0-beta
```
Pushing a v* tag runs the Release workflow (.github/workflows/release.yml), which builds the macOS zip, the DMG, and latest.json on a fresh runner and publishes them to a GitHub Release automatically. No manual upload, no secrets — the workflow uses GitHub's built-in GITHUB_TOKEN, and the app itself checks the public GitHub API unauthenticated.
Existing users get an auto-popping update window within 6h (or on next launch) offering one-click Update & Restart.

Manual fallback (no CI):

make release VERSION=0.3.0-beta — produces the zip, the DMG, and latest.json.
Publish a GitHub release tagged v0.3.0-beta, and attach:
- ClashGO-v0.3.0-beta-macOS.zip
- latest.json

🤝 HELP WANTED (Porting to Windows)

Right now, this is heavily tested on macOS. I'd love some help porting/testing this for Windows. If you're a dev and want to help me make this not-just-a-Mac-thing, open a PR or hit me up!

Also, if you find bugs (you will), just open an issue.

📄 License

MIT. Do whatever you want with it.

Documentation ¶

There is no documentation for this package.

Source Files ¶

View all Source files

Directories ¶

?	: This menu
/	: Search site
f or F	: Jump to
y or Y	: Canonical URL

Path	Synopsis
cmd
attack_record command cmd/attack_record is a MACRO RECORDER + REPLAYER for ClashGO.	cmd/attack_record is a MACRO RECORDER + REPLAYER for ClashGO.
attack_report command Command attack_report answers the two questions a finished attack actually raises, from the run's own log:	Command attack_report answers the two questions a finished attack actually raises, from the run's own log:
attack_verify command Command attack_verify is the 720p review harness: it proves the attack plan is correct BEFORE a battle is spent on it, by rendering exactly what the bot would tap onto a live (or saved) 720p battle screenshot.	Command attack_verify is the 720p review harness: it proves the attack plan is correct BEFORE a battle is spent on it, by rendering exactly what the bot would tap onto a live (or saved) 720p battle screenshot.
capture_template command cmd/capture_template is a manual template-recapture tool.	cmd/capture_template is a manual template-recapture tool.
classify_probe command Command classify_probe classifies a screenshot (default: live adb capture) with the repo's own classifier and prints the score for every state rule plus a few key pixel reads, so a stuck bot can be diagnosed from what the vision layer actually sees.	Command classify_probe classifies a screenshot (default: live adb capture) with the repo's own classifier and prints the score for every state rule plus a few key pixel reads, so a stuck bot can be diagnosed from what the vision layer actually sees.
design_attack command cmd/design_attack is the one-stop tool for authoring + verifying the per-unit `formula.json` consumed by the deploy pipeline.	cmd/design_attack is the one-stop tool for authoring + verifying the per-unit `formula.json` consumed by the deploy pipeline.
pick_coords command Command pick_coords is the deploy-point picker: it shows the live emulator frame in the Preview tab and lets you click the exact points the bot should use, per side, then writes them into precision_config.json.	Command pick_coords is the deploy-point picker: it shows the live emulator frame in the Preview tab and lets you click the exact points the bot should use, per side, then writes them into precision_config.json.
release_manifest command Command release_manifest emits a `latest.json` file for the just-built release zip.	Command release_manifest emits a `latest.json` file for the just-built release zip.
resprobe command Command resprobe measures how the CoC HUD scales between two framebuffer geometries.	Command resprobe measures how the CoC HUD scales between two framebuffer geometries.
result_probe command Command result_probe is a diagnostic harness that runs the bot's own battle-result OCR pipeline against a saved screenshot (defaults to last_battle_result.png in the config dir).	Command result_probe is a diagnostic harness that runs the bot's own battle-result OCR pipeline against a saved screenshot (defaults to last_battle_result.png in the config dir).
screendump command
see command Command see is the debugging agent's eyes on the emulator.	Command see is the debugging agent's eyes on the emulator.
swipe_probe command Command swipe_probe is a standalone live-verification harness for the human-gesture input layer (Phase 1 of the autonomous hardening loop): it connects to the emulator like the bot does and exercises the sendevent bezier-swipe primitives against the live device.	Command swipe_probe is a standalone live-verification harness for the human-gesture input layer (Phase 1 of the autonomous hardening loop): it connects to the emulator like the bot does and exercises the sendevent bezier-swipe primitives against the live device.
test_wall_upgrade command cmd/test_wall_upgrade is a manual verification tool for the wall-upgrade system.	cmd/test_wall_upgrade is a manual verification tool for the wall-upgrade system.
tplprobe command Command tplprobe locates one stored template on a frame across a scale sweep and prints the ranked result.	Command tplprobe locates one stored template on a frame across a scale sweep and prints the ranked result.
wedge_probe command
wmresize command Command wmresize changes a running device's display geometry.	Command wmresize changes a running device's display geometry.
internal
adb Package adb — bootprobe.go	Package adb — bootprobe.go
attack
attacklog Package attacklog turns a bot run log into a per-unit account of what the deploy phase actually did.	Package attacklog turns a bot run log into a per-unit account of what the deploy phase actually did.
bot Package bot — boot_report.go	Package bot — boot_report.go
config
game Package game — chestdismiss.go	Package game — chestdismiss.go
logger
paths Package paths resolves absolute, writable locations for the bot's runtime files.	Package paths resolves absolute, writable locations for the bot's runtime files.
updater Package updater polls GitHub Releases for new ClashGO versions, downloads updates with SHA256 verification, and signals the UI / applies updates on demand.	Package updater polls GitHub Releases for new ClashGO versions, downloads updates with SHA256 verification, and signals the UI / applies updates on demand.
vision Digit classification against canonical-size templates.	Digit classification against canonical-size templates.
pkg
formula Package formula defines the per-unit deploy coordinate schema produced by the `design_attack` interactive tool and consumed by the deploy pipeline in `internal/attack`.	Package formula defines the per-unit deploy coordinate schema produced by the `design_attack` interactive tool and consumed by the deploy pipeline in `internal/attack`.
strategy