Tandem Mode

English | Srpski

Terminalski coding agent napravljen posebno za DeepSeek API — ne generički LLM harness u koji je DeepSeek naknadno ugurana. Interaktivni REPL, planner/worker/reviewer orkestracija, cache-aware arhitektura prompta, i podjednaka podrška za Windows, macOS i Linux.

Nezavisan open-source projekat. Nije povezan sa DeepSeek-om niti od njega podržan.

Status

M0–M4 iz plana razvoja su gotovi. Objavljen na npm-u, upotrebljiv već danas za stvarne coding zadatke nad lokalnim repozitorijumom.

Prvi benchmark je gotov — pun izveštaj u docs/benchmark-results.md (na engleskom; srpska verzija: docs/benchmark-results.sr.md). Ukratko: sve tri konfiguracije (Pro-only, Flash-only, orkestracija) su ispravno rešile 4/4 ubačena bага u pravom WooCommerce pluginu, sa čistim php -l i nula nepotrebnih izmena. Ali za ovu klasu zadatka (mali, jednodatotečni fixevi) orkestracija je koštala ~9.5× više i trajala ~19× duže od Pro-only, za isti kvalitet — suprotno onome zbog čega bi se orkestracija tražila. Čitati kao: overhead orkestracije treba veći, razdvojiv zadatak da bi se isplatio, a ovaj prvi test to nije proverio. Prijavljeno onako kako jeste, ne prilagođeno očekivanjima.

Šta ima

• Agentic petlja — deepseek-v4-pro/deepseek-v4-flash sa tool-calling: read_file, list_dir, search, edit, git_diff, shell, view_image, web_search.
• Dva načina rada — interaktivni REPL za svakodnevni rad, single-shot mod (tandem "task" --yes) za skriptovanje i CI.
• Orkestracija (/plan) — planner pravi JSON listu taskova, workeri izvršavaju svaki task sa svežim minimalnim kontekstom, reviewer proverava git diff naspram originalnog zadatka i ili odobrava ili traži korekcije (ograničeno sa max_review_loops).
• Cache-aware promptovi — sistemski prompt workera + repo mapa + plan ostaju bajt-za-bajt identični kroz pozive u jednoj orkestraciji, tako da DeepSeek-ov keš stvarno pogađa. Izmereno uživo: cache-hit tokeni su rasli iz poziva u poziv unutar jednog /plan pokretanja.
• Vision — view_image omogućava agentu da pogleda screenshot na koji ga uputiš; /paste uzima sliku direktno iz clipboard-a (Windows, macOS, i Linux preko X11/xclip ili Wayland/wl-clipboard).
• Web search — izolovani pozivi ka DeepSeek Responses API-ju kad agentu treba nešto van repozitorijuma (error poruka, dokumentacija biblioteke).
• Perzistencija sesije — svaka sesija je JSONL fajl; /resume nastavlja poslednju (ili navedenu), /fork grana bez diranja originalne.
• Bezbednost — destruktivne akcije (izmene fajlova, shell komande van male read-only bele liste) uvek traže potvrdu; y/n/a gde a pamti izbor za taj alat do kraja sesije. --yes preskače ovo za CI, ali uvek ispisuje šta je automatski odobreno.
• Kontrola troškova — usage se čita isključivo iz API-jevog usage polja, nikad se ne procenjuje. Budžet (/budget, --budget) zaustavlja petlju pre sledećeg poziva ako se pređe, bez gubitka sesije. /usage takođe pokazuje koliko bi sesija koštala off-peak, a REPL upozorava pri startu ako si trenutno u peak periodu.
• ESC za prekid — čisto prekida poziv u toku (i bilo koju shell komandu koja radi), čuvajući ono što je do tada generisano.
• Cross-platform — shell alat pokreće PowerShell nativno na Windows-u i sh na macOS/Linux-u, izmene fajlova čuvaju originalni CRLF/LF stil, putanje se svuda tretiraju preko path.resolve.

Brzi početak

npm install -g tandem-mode
tandem            # interaktivni REPL
tandem "objasni sta radi ovaj repo" --yes   # jedan potez

Ili iz izvornog koda (korisno za doprinose, ili da pratiš main umesto poslednje npm verzije):

git clone https://github.com/zdrave08/Tandem-Mode.git
cd Tandem-Mode
pnpm install
pnpm dev            # interaktivni REPL
pnpm dev "objasni sta radi ovaj repo" --yes   # jedan potez

Pri prvom pokretanju bićeš pitan za DeepSeek API ključ (napravi ga na platform.deepseek.com) i podrazumevani model/reasoning effort. Ključ se čuva u OS-ovom bezbednom skladištu kredencijala — nikad u config fajlu ili logu:

• Windows — DPAPI-šifrovan (vezan za tvoj OS nalog) u %LOCALAPPDATA%\TandemMode\credentials.dat.
• macOS — login Keychain, preko ugrađenog security CLI-ja.
• Linux — Secret Service (gnome-keyring, KWallet ili slično), preko secret-tool (instaliraj libsecret-tools ako nedostaje).

DEEPSEEK_API_KEY radi svuda i uvek ima prioritet, za CI upotrebu.

Upotreba

tandem                              # interaktivni REPL
tandem "popravi off-by-one u foo.ts"
tandem --plan "dodaj dark mode na stranicu podešavanja"
tandem "task" --model deepseek-v4-flash --effort low --budget 0.50 --yes

| Flag | Efekat | |---|---| | --resume / -r | Nastavi poslednju sesiju u ovom direktorijumu | | --yes / -y | Automatski odobri destruktivne akcije (ispisuje šta je odobreno) | | --plan | Pokreni planner/worker/reviewer orkestraciju umesto jednog poteza | | --model | deepseek-v4-pro ili deepseek-v4-flash | | --effort | low, high, ili max reasoning effort | | --budget | Tvrd USD limit za pokretanje | | --max-review-loops | Limit korekcionih ciklusa u orkestraciji (podrazumevano 3) |

REPL komande

| Komanda | Efekat | |---|---| | /plan <zadatak> | Planner/worker/reviewer orkestracija | | /model [ime] | Prikaži ili promeni model | | /thinking [on\|off] | Uključi/isključi thinking mode | | /effort [low\|high\|max] | Prikaži ili postavi reasoning effort | | /status | Trenutna sesija/podešavanja | | /diff [--staged] [putanja] | Diff radnog stabla, bez API poziva | | /usage | Tokeni, cena, off-peak projekcija | | /budget [iznos] | Prikaži ili postavi budžet sesije | | /new | Nova sesija | | /save-profile <ime> | Sačuvaj model, effort, budžet i review krugove kao imenovan profil | | /profile [ime] | Učitaj sačuvan profil, ili prikaži listu | | /compact | Sažmi istoriju u novu sesiju da se oslobodi kontekst; stara sesija ostaje na disku | | /fork | Nova sesija sa kopijom trenutne istorije | | /resume [id] | Nastavi poslednju (ili navedenu) sesiju | | /paste [poruka] | Pošalji sliku iz clipboard-a agentu | | /clear | Očisti ekran | | /help | Ova lista | | /exit | Izlaz |

Pritisni ESC u bilo kom trenutku tokom poteza da ga prekineš.

Arhitektura

tandem (bez argumenata) ─┬─> interaktivni REPL ─┬─> jedan potez: agent petlja (alati)
                          │                      └─> /plan: planner → worker(i) → reviewer
tandem "task"     ────────┘   (single-shot, ista agent petlja, za skripte/CI)

• src/deepseek/ — tanak klijent za DeepSeek-ov OpenAI-kompatibilan API (streaming + non-streaming chat completions, vision, web search preko Responses API-ja). Vidi docs/api-notes.md za ponašanje API-ja protiv kog je ovo napravljeno, verifikovano uživo, ne pretpostavljeno.
• src/agent/ — tool-calling petlja, implementacije alata, perzistencija sesije, praćenje usage/troška.
• src/orchestrator/ — planner/worker/reviewer, generisanje repo mape, cache-aware konstrukcija stabilnog prefiksa.
• src/repl/ — slash komande, runtime konfiguracija, first-run wizard.
• src/cli.tsx — Ink terminalski UI i REPL/single-shot ulazne tačke.

Konfiguracija

Slojevito: sesija (komande u REPL-u) > projekat (.tandem/config.json u trenutnom direktorijumu) > globalno (~/.tandem/config.json).

{
  "defaultModel": "deepseek-v4-pro",
  "defaultReasoningEffort": "high",
  "budgetUsd": 5,
  "maxReviewLoops": 3,
  "verifyCommand": "pnpm typecheck && pnpm test",
  "notifyCommand": "curl -s -d \"Tandem: $TANDEM_OUTCOME\" https://ntfy.sh/my-topic",
  "language": "sr"
}

verifyCommand se pokreće pre svakog /plan review kruga, a njegov rezultat ide reviewer-u. language je jezik interfejsa (en ili sr, podrazumevano en); --lang flag i TANDEM_LANG env promenljiva ga nadjačavaju, tim redom. First-run wizard ga pita.

notifyCommand se pokreće kad se /plan završi: reviewer odobrio, dostignut max_review_loops, ili greška (ne i kad ga prekineš sa ESC). Detalji dolaze kao promenljive okruženja, nikad ubačeni u tekst komande: TANDEM_OUTCOME (approved, max_review_loops ili error), TANDEM_TASK, TANDEM_NOTES (beleške reviewer-a, ili poruka greške), TANDEM_REVIEW_LOOPS i TANDEM_COST_USD. Komanda radi u tvojoj školjki (PowerShell na Windows-u, sh drugde) sa limitom od 15 s, a neuspeh samo ispiše upozorenje. Može bilo koja shell komanda, pa su Slack, ntfy, desktop obaveštenje ili webhook samo primeri:

{ "notifyCommand": "curl -s -d \"Tandem: $TANDEM_OUTCOME\" https://ntfy.sh/my-topic" }

Na Windows-u (PowerShell) promenljive se pišu $env:TANDEM_OUTCOME.

Kao i verifyCommand, notifyCommand se pokreće bez pitanja, pa ga stavljaj u .tandem/config.json projekta samo ako tom projektu veruješ.

Profili: /save-profile <ime> čuva trenutni model, reasoning effort, budžet i review krugove u ~/.tandem/profiles/<ime>.json, a /profile <ime> ih vraća u sesiju koja radi (primenjuju se samo polja koja postoje u fajlu). /profile bez argumenta prikazuje sačuvane. Imena koriste a-z, 0-9, - i _. Profili nikad ne sadrže verifyCommand ni API ključ.

API ključ se nikad ne čuva u ovim fajlovima — živi u OS-ovom skladištu kredencijala (ili u DEEPSEEK_API_KEY env promenljivoj, koja ima prioritet, za CI upotrebu).

Razvoj

Vidi CONTRIBUTING.sr.md.

pnpm install
pnpm typecheck
pnpm dev "neki zadatak"

Disclaimer

Ovo je nezavisan projekat koji vodi zajednica. Nije povezan sa DeepSeek-om, niti od njega podržan ili sponzorisan.

Licenca

MIT