auto-continue-cli-agent

  ┏━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
  ┃   a ( c∞c ) a   ·  acca     ┃
  ┃   auto-continue cli agent   ┃
  ┗━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┛
  never lose a session to a limit.

a·c∞c·a · acca — usage-aware auto-continue for Claude Code & Antigravity CLI.

Supervisor lokal yang memonitor usage dan melanjutkan otomatis sesi yang terputus karena limit untuk dua CLI coding-agent: Claude Code dan Antigravity CLI.

---

English summary

The documentation in this repository is written in Indonesian. This section is the English entry point.

acca is a local supervisor for two long-running coding-agent CLIs — Claude Code and Antigravity CLI. Both enforce usage limits (a rolling 5-hour window plus a weekly quota), and hitting one stops a session mid-task. acca watches usage through each tool's official channels, detects when a session stalls on a limit, and resumes it automatically once the window resets — injecting an explicit continue instruction into a live session, or resuming a dead one by id in its original working directory.

Design constraints, in short:

• Human-in-the-loop, never autonomous. Automatic actions are limited to resume/continue/probe/verify on sessions that already exist. The supervisor never invents instructions (ADR-008).
• Agent output is data, not commands. Nothing branches on the content of a CLI transcript — a prompt-injection firewall, since transcripts can contain text from the open web (ADR-013).
• Local by default. State lives in a local SQLite database, network egress is restricted to an in-code allowlist, and there is no telemetry. The optional web dashboard (acca web) is read-only and binds to 127.0.0.1 only.

Status: pre-release (0.x), not published to any package registry. Install is from source; see Instalasi — the commands there are language-neutral. Runs on Linux and Windows 11 (systemd --user / Task Scheduler at logon).

Start here: SECURITY.md (trust model and what acca touches on your machine) · LICENSE (Apache 2.0) · CHANGELOG.md · docs/DECISIONS.md (architecture decision records — the headings are readable even without Indonesian).

This repository is also a worked example of a doc-first workflow — see Metodologi below.

Not affiliated with, endorsed by, or supported by Anthropic or Google. acca is an independent tool that drives their command-line clients as a user would. "Claude Code" and "Antigravity" belong to their respective owners.

---

Masalah

Sesi agent panjang sering terhenti di tengah jalan karena kehabisan usage:

• Claude Code — limit rolling 5-jam + limit mingguan per akun.
• Antigravity CLI — refresh 5-jam + kuota mingguan (dua-duanya harus > 0).

Ketika limit habis, sesi berhenti. Progres tidak hilang (transcript tersimpan), tapi user harus: menyadari sesi berhenti → tahu kapan limit reset → kembali ke folder yang benar → resume manual. Untuk solo dev yang menjalankan agent berjam-jam, ini biaya waktu + konteks yang nyata.

Detail (untuk siapa, biaya masalah terukur, batasan) → docs/PROJECT.md.

Solusi (ringkas)

1. Monitor — pantau status usage kedua CLI.
2. Detect — kenali saat sesi berhenti karena limit + baca kapan window reset.
3. Auto-continue — jadwalkan resume (claude --resume <id> / padanan Antigravity) begitu limit pulih, di working directory yang benar.

Instalasi (dari source)

Belum ada paket/installer rilis — jalankan dari source. Cross-OS (Linux + Windows). npm install men-trigger build otomatis (script prepare → npm run build) — tak perlu jalankan npm run build terpisah kecuali rebuild manual setelah edit source (lihat Update acca).

Sudah punya clone repo ini (Linux / macOS / Git Bash):

npm install
npm link                        # sekali — bikin perintah `acca` tersedia di PATH

Windows PowerShell — && tidak ada di Windows PowerShell 5.1 (bawaan Windows 11; baru ada di PowerShell 7), jadi pisahkan perintahnya:

npm install
npm link                        # sekali — bikin perintah `acca` tersedia di PATH

npm link memasang shim global (bin.acca → dist/cli/index.js). Cabut kapan saja: npm unlink -g auto-continue-cli-agent.

Tanpa npm link (kalau tak mau shim global) — semua perintah di bawah tetap jalan dengan memanggil entrypoint langsung. Ganti acca dengan node dist/cli/index.js, mis. node dist/cli/index.js daemon.

Perintah acca hanya ada setelah npm link (atau npm i -g .). Kalau muncul 'acca' is not recognized / command not found, itu sebabnya — bukan build yang gagal.

Mesin baru, belum ada clone (setup lintas-mesin)

Repo ini private — mesin baru butuh git ter-otorisasi ke GitHub sekali (gh auth login lalu gh auth setup-git, atau SSH key terdaftar) sebelum git clone jalan.

git clone https://github.com/ziffan/auto-continue-cli-agent.git ~/acca
cd ~/acca
npm install                     # trigger build otomatis (script "prepare")
npm link                        # `acca` tersedia di PATH
acca --version                  # verifikasi

Native addon (node-pty, better-sqlite3) di-compile ulang saat npm install — mesin butuh toolchain build native (Linux: build-essential/setara; Windows: Visual Studio Build Tools "Desktop development with C++"). Kalau native module gagal jalan meski npm install "sukses" tanpa error, lihat G-11 (docs/GOTCHAS.md) — ada kelas kegagalan senyap (allow-scripts) yang butuh verifikasi eksplisit.

Jangan pakai npm install -g git+https://… (shortcut satu-baris tanpa clone manual) — diuji langsung dan tidak andal: npm menjalankan lifecycle prepare dua kali untuk git-dependency + instalasi global, dan pada salah satu jalurnya node_modules/.bin (termasuk tsc) belum terpasang saat prepare jalan → gagal sh: tsc: not found (bug npm, bukan config repo ini). git clone manual + npm install di atas tidak kena masalah ini (raw npm install di direktori proyek sendiri selalu memasang dependencies dan devDependencies dengan urutan benar) — sudah diuji ulang bersih dari clone segar.

Setelah acca terpasang, lanjut ke Menjalankan daemon untuk pasang sebagai service (systemd --user di Linux / Task Scheduler autostart di Windows) supaya jalan tanpa terminal terbuka.

Perintah (yang sudah ada)

Perintah	Fungsi
acca run <claude|agy> [args…]	Jalankan CLI target di bawah supervisor (PTY wrapper); catat sesi + deteksi limit.
acca daemon	Supervisor daemon: rekonsiliasi orphan, scheduler resume, monitor usage periodik, IPC.
acca status	Sesi termonitor + usage best-effort (bar per window, indikator "perkiraan").
acca log [sessionId]	Riwayat event / audit trail (terbaru dulu).
acca web [--port <n>]	Web UI monitor read-only di browser (http://127.0.0.1:<port>, default 4599). Mirror status/usage/sesi/log, auto-refresh. Opt-in; bind loopback saja (ADR-028).
acca prune [ids…] [--all] [--force] [--dry-run]	Arsipkan sesi (soft, tak hapus — ADR-004) agar status tetap relevan. Default: sesi terminal saja (sisakan RUNNING/LIMIT_HIT); reversible.

Belum ada: kontrol Telegram (M-remote — DITUNDA) & resume-now/cancel via remote; aksi kontrol via Web UI (v1 read-only saja).

Menjalankan daemon

Auto-resume hanya jalan bila daemon hidup saat window limit reset. Daemon harus jalan sebagai kamu — ia memakai acca.db di profil kamu dan mewarisi sesi login claude/agy kamu (ADR-005).

Sekarang (semua OS) — manual:

acca daemon                      # biarkan terminal ini terbuka
# tanpa npm link: node dist/cli/index.js daemon

Linux — service (systemd --user + lingering): ini jalur always-on yang didukung; jalan sebagai user kamu (bukan root) → $HOME, acca.db, dan kredensial claude/agy yang sama (justru asimetri inilah yang aman di Linux tapi tidak di Windows — lihat I-33). Pasang:

npm run build              # pastikan dist/ ada
sh scripts/install-linux.sh   # render unit + enable --now + loginctl enable-linger
systemctl --user status acca-daemon        # verifikasi active (running)
journalctl --user -u acca-daemon -f        # log
# cabut: sh scripts/uninstall-linux.sh   (service disabled + unit dihapus; acca.db & backups aman)

Restart=on-failure + RestartSec=5 → daemon auto-restart <30s bila crash; enable-linger → jalan tanpa sesi login (survive logout, auto-start saat boot).

Windows — autostart per-user (Task Scheduler @logon), BUKAN Windows Service (ADR-026). Jalur always-on Windows = Task Scheduler trigger "At log on" yang jalan sebagai user login kamu (nol admin, task per-user) → $HOME, acca.db, dan kredensial claude/agy yang sama dengan sesi kamu. Pasang (PowerShell):

npm run build                                                        # pastikan dist\ ada
powershell -ExecutionPolicy Bypass -File scripts\install-windows.ps1   # daftar task autostart @logon (per-user, nol admin)
Get-ScheduledTask acca-daemon | Get-ScheduledTaskInfo                # verifikasi
Start-ScheduledTask -TaskName acca-daemon                            # jalankan sekarang (tak perlu tunggu logon)
# cabut: powershell -ExecutionPolicy Bypass -File scripts\uninstall-windows.ps1   (task dihapus; acca.db & backups aman)

Watchdog repetisi (Repetition PT1M + IgnoreNew) → daemon crash auto-restart ~60-90s (floor Task Scheduler = 1 menit, bukan <30s spt systemd — G-49); run-hidden (nol jendela konsol); ExecutionTimeLimit=PT0S (daemon long-running tak di-kill). Scope jujur: logon-scoped — daemon jalan selama kamu login, tak lintas-logout / at-boot-pra-login (direlakan untuk profil laptop; always-on sejati = Linux systemd). Kenapa BUKAN Windows Service: default LocalSystem → me-resolve acca.db berbeda (…\systemprofile\…, DB kosong baru) + tak lihat kredensial kamu → daemon menatap DB kosong, sc query/acca status tampak normal tapi tak berbuat apa-apa saat limit reset (menipu). Detail: I-33/ADR-026 (docs/ISSUES.md, docs/DECISIONS.md).

Batasan (semua OS, ADR-007): kalau mesin tidur/mati, resume tertunda sampai ia bangun.

Update acca (setelah ada commit baru)

acca daemon (service) jalan dari dist/ — bukan langsung dari source. git pull saja tidak cukup; dist/ basi sampai kamu npm run build ulang + restart proses yang jalan (service tak auto-reload).

Linux — service (systemd --user):

git pull                                    # atau: git fetch && git status  dulu kalau ada kerja lokal
npm install                                 # kalau ada dependency baru (aman dijalankan selalu)
npm run build                               # rebuild dist/ dari source terbaru
systemctl --user restart acca-daemon        # daemon lama berhenti, yang baru pakai dist/ terbaru
systemctl --user status acca-daemon --no-pager   # verifikasi: active (running), PID baru
journalctl --user -u acca-daemon --since "1 minute ago" --no-pager   # cek log start bersih, nol error
acca status                                 # dogfood check — daemon HIDUP + heartbeat baru

Windows — Task Scheduler (autostart per-user):

git pull
npm install
npm run build
Stop-ScheduledTask -TaskName acca-daemon
Start-ScheduledTask -TaskName acca-daemon
Get-ScheduledTask acca-daemon | Get-ScheduledTaskInfo   # verifikasi LastTaskResult / LastRunTime

Aman kapan pun: restart daemon tidak menghapus state — sesi & job terjadwal ada di acca.db (SQLite), daemon me-reconcile ulang saat start (AC-7). Cek dulu acca status sebelum restart kalau mau tahu ada sesi RUNNING/LIMIT_HIT yang sedang dipantau (restart tidak membunuhnya — proses acca run target CLI-nya terpisah dari daemon, ADR-017 — tapi tetap baik untuk tahu kondisi sebelum menyentuh service).

Kalau perintah acca belum ada di PATH (command not found / 'acca' is not recognized): jalankan npm link sekali (lihat Instalasi di atas) — ini terpisah dari update di atas, cukup dilakukan sekali per mesin, bukan tiap update.

Web UI monitor (opt-in, read-only)

Pantau usage/sesi/log di browser lokal — mirror acca status yang auto-refresh (ADR-028).

acca web                    # http://127.0.0.1:4599  (Ctrl-C untuk berhenti)
acca web --port 8080        # atau set env ACCA_WEB_PORT

Read-only + aman: bind 127.0.0.1 saja (bukan LAN), hanya GET / + GET /api/status, nol aksi (tak ada resume/cancel via web). Endpoint memakai proyeksi ter-firewall yang sama dengan IPC status — tak membocorkan cli_session_id/cwd/rahasia; Host non-loopback ditolak (guard DNS-rebinding); halaman 100% self-contained (nol aset eksternal). Threat model: docs/THREAT-MODEL.md §9.

Membersihkan sesi (acca prune)

acca status menumpuk sesi lama (EXITED/RESUMED/…). acca prune mengarsipkannya supaya tampilan tetap relevan.

acca prune                  # arsip sesi TERMINAL saja; sisakan RUNNING/LIMIT_HIT
acca prune --dry-run        # lihat yang akan diarsip tanpa mengubah
acca prune <id> [<id>…]     # arsip sesi tertentu (dipantau/hidup butuh --force)
acca prune --all            # arsip SEMUA sesi aktif (termasuk yang dipantau)

Soft-archive, bukan hapus (ADR-004): hanya menyetel archived_at → sesi hilang dari status tapi row tetap ada di DB (audit events + retensi never-purge); reversible. Setiap arsip tercatat di acca log (session_archived from=<status> source=prune).

Backup & restore

Apa yang di-backup: acca.db (checkpoint WAL TRUNCATE + salin file utama saja — sidecar -wal/-shm basi pasca-checkpoint TAK disalin, salinan konsisten diverifikasi integrity_check). Retensi tiered GFS-lite (ADR-024): 24 snapshot terbaru (hourly) + 1 representatif per hari-kalender lokal untuk 30 hari terakhir yang punya snapshot — coverage 1 bulan, disk ter-cap ~54× ukuran DB. Lokasi default <dataDir>/backups (override env ACCA_BACKUP_DIR). Config via env (config-over-hardcode, ADR-022/024): ACCA_BACKUP_RETENTION_HOURLY (default 24), ACCA_BACKUP_RETENTION_DAILY (default 30), ACCA_DATA_DIR, ACCA_BACKUP_DIR.

Jalankan sekali manual:

npm run build           # wajib — skrip mengimpor dist/
node scripts/backup.js

Pasang jadwal otomatis (default interval hourly, ADR-024):

OS	Template
Linux (systemd --user)	deploy/backup/systemd/ — acca-backup.service (oneshot) + acca-backup.timer (OnCalendar=hourly)
Windows (Task Scheduler)	deploy/backup/windows/register-backup-task.ps1 — trigger repetition 1 jam

Backup = tugas one-shot periodik, bukan proses long-running — Task Scheduler cocok di sini. (Kelemahan Task Scheduler yang mendasari ADR-021 — gagal-senyap tanpa auto-restart — khusus relevan untuk daemon yang harus terus hidup; tidak berlaku untuk job one-shot yang memang dirancang exit setiap kali selesai.) Detail placeholder path + variabel ada di komentar tiap template.

Restore (langkah manual):

1. Hentikan daemon. Linux: systemctl --user stop acca-daemon. Windows (autostart Task Scheduler, ADR-026): Stop-ScheduledTask -TaskName acca-daemon (bila watchdog repetisi aktif, Disable-ScheduledTask dulu supaya tak re-start saat restore) — atau Ctrl+C bila jalan manual acca daemon.
2. Ganti <dataDir>/acca.db dengan snapshot pilihan: cp <snapshot> <dataDir>/acca.db — hapus sisa <dataDir>/acca.db-wal / -shm bila ada.
3. Jalankan daemon lagi (acca daemon, atau systemctl --user start acca-daemon di Linux pasca-M5.4).
4. Verifikasi: acca status menunjukkan daemon hidup + sesi termonitor sesuai snapshot.

[LIVE] butuh user — alur restore end-to-end (backup asli → restore → daemon start bersih) belum diverifikasi live di mesin nyata; jangan anggap terverifikasi sampai dijalankan manual.

Kenapa ini bukan hal sepele

• Usage Claude Code kini terekspos resmi (statusLine JSON v2.1.80+), dan deteksi limit bisa event-driven via hook StopFailure (v2.1.78+) — tapi dua-duanya hanya bekerja pada sesi yang di-manage; dan limit-hit tidak men-exit sesi interaktif (proses idle di prompt), sementara sesi yang benar-benar mati (reboot/tutup terminal) tak bersinyal apa pun — supervisor harus menangani dua kondisi berbeda: inject "continue" ke sesi hidup vs resume-by-id sesi mati. Lihat docs/RESEARCH.md §2c.
• Resume Claude Code scoped ke working directory sesi — harus cd ke folder asli.
• Kuota Antigravity variabel (berkorelasi beban kerja per-prompt), dan /usage-nya snapshot saat launch, bukan live — probe kuota harus dirancang khusus.

Prior art & posisi

• CodexBar — monitor usage 56+ provider (menu bar macOS-only, Swift), monitor-only tanpa auto-resume. Kini sudah mendukung Antigravity (isu #1178 ditutup via PR #1341) — mekanismenya (probe language-server lokal + endpoint OAuth retrieveUserQuota) justru jadi referensi implementasi untuk probe kita.
• claude-auto-retry — auto-continue Claude Code via tmux (deteksi pesan limit → tunggu reset → kirim "continue"). Claude Code-only, butuh tmux, tanpa native Windows, tanpa monitor usage, dan hanya menangani sesi yang masih hidup di pane.

Diferensiasi kita: monitor + auto-continue sesi hidup (PTY sendiri, tanpa tmux) + resume sesi yang sudah mati (claude-auto-retry hanya menangani pane hidup), cross-OS native (Linux + Windows tanpa WSL/tmux), dual-CLI (Claude Code + Antigravity), state persisten + audit trail. Catatan risiko: auto-continue native sedang diminta ke upstream Claude Code (tracking #13354, masih open per 11 Jul 2026, demand naik — banyak isu duplikat, belum ada implementasi native di changelog) — lihat docs/RESEARCH.md §4c/§5b–§5c.

Dokumentasi

Dokumen	Isi
docs/PROJECT.md	Problem statement, persona, user story, flow, wireframe, acceptance criteria
docs/RESEARCH.md	Fakta usage-limit & mekanisme resume kedua CLI + sumber
docs/ARCHITECTURE.md	C4, container map, tech stack
docs/DECISIONS.md	ADR (locked / pending)
docs/NFR.md	Target non-fungsional terukur
docs/THREAT-MODEL.md	Threat model remote (Telegram) + fondasi lokal (§8) + Web UI ingress (§9)
docs/BRANDING.md	Identitas visual acca (wordmark/splash + inline badge, gating ADR-027)
docs/MILESTONES.md	Rencana milestone + progres
docs/GOTCHAS.md	Jebakan teknis yang sudah dibayar (agy/CC/PTY/store)
docs/CONTEXT.md	Status proyek (update tiap sesi)
docs/ISSUES.md	Issue terbuka/tertutup + prioritas

Metodologi doc-first (repo ini sebagai demonstrasi)

Repo ini bukan cuma alat — ia artefak demonstrasi dari metode kerja doc-first yang saya bahas di kampusmerah.com. Kalau kamu datang dari tulisan itu, di sinilah metodenya bisa diperiksa apa adanya, termasuk bagian yang tidak rapi.

Aturan intinya satu: tak ada kode fitur sebelum spec LOCKED. Keputusan dibuat di dokumen, lalu kode menyusul — bukan sebaliknya. Turunannya terlihat di struktur repo:

• docs/DECISIONS.md — ADR bergaya Nygard (Context → Decision → Consequences → Alternatives Rejected). ADR ber-status Accepted bersifat immutable: revisi = ADR baru yang men-supersede, bukan edit diam-diam. Contoh nyata ada di repo ini — ADR-018 dibatalkan ADR-019 setelah verifikasi live membuktikan premisnya salah, dan jejak kesalahannya sengaja dibiarkan terbaca.
• docs/GOTCHAS.md — katalog jebakan yang sudah dibayar mahal, satu baris per temuan, detail di arsip. Ini yang membuat sesi kerja berikutnya (manusia atau agent) tak mengulang biaya yang sama.
• docs/THREAT-MODEL.md + docs/NFR.md — keamanan dan target non-fungsional ditulis sebagai kontrak yang bisa diuji, lalu di-gate di test/security-*.test.ts, bukan jadi niat baik di kepala penulis.
• docs/CONTEXT.md — status ditulis ulang tiap akhir sesi, karena konteks agent hilang antar-sesi dan ingatan manusia juga tidak lebih baik.
• .claude/skills/ — ritual kerjanya sendiri ikut di-version-control (buka sesi, tutup sesi, tulis ADR, tier-review sebelum commit, pecah vertical slice). Ini sengaja ikut publik: metode yang tak bisa diperiksa orang lain bukan metode, cuma klaim.

Jujur soal ongkosnya: dokumen di repo ini lebih banyak dari kodenya, dan itu memang mahal di awal. Yang dibeli dengan ongkos itu adalah keputusan yang tidak di-relitigasi tiap sesi baru, dan agent yang bisa melanjutkan pekerjaan tanpa mengarang konvensinya sendiri. Untuk proyek eksperimen sekali-pakai, ini berlebihan — pilih sadar-sadar.

Konteks agent

CLAUDE.md adalah satu sumber konteks untuk semua coding agent. AGENTS.md adalah symlink ke CLAUDE.md supaya Codex/Cursor/Windsurf/OpenCode dan Claude Code berbagi instruksi yang sama.

Lisensi & dukungan

Dilisensikan di bawah Apache License 2.0 — lihat LICENSE untuk teks lengkap dan NOTICE untuk atribusi.

Copyright 2026 Ziffany Firdinal.

Dibuat di kampusmerah.com — workshop dev pribadi, brand payung untuk project independent. Author: ziffany.firdinal.my.id.