🇮🇩 Bahasa Indonesia

Melfic Agent adalah CLI AI coding agent yang beneran agentic — bukan sekadar chatbot. Command-nya ai. Melfic memahami struktur & arsitektur project tempat kamu berada, membaca dan mengubah file, menjalankan command shell, dan mengingat percakapan secara lokal. Dibangun supaya nyaman dipakai di Termux (Android), tanpa laptop atau root, dan mendukung Gemini maupun OpenRouter pakai API key kamu sendiri.

ai buat folder bernama s3raph lalu npm init
ai perbaiki error di project ini
ai tambahkan authentication ke project ini

Gak perlu tanda kutip — semua teks setelah ai dianggap satu instruksi bahasa natural.

Install

Di Termux (Android)

pkg update
pkg install nodejs unzip
termux-setup-storage
cd ~
unzip ~/storage/downloads/melfic-agent.zip -d ~
cd ~/melfic-agent
npm install -g .

Gak perlu compiler tambahan — memory lokal pakai node:sqlite bawaan Node.js, yang butuh Node.js 22.5 ke atas. Cek dengan node -v; kalau lebih lama, pkg install nodejs lagi (Termux biasanya udah versi baru) atau coba pkg install nodejs-lts.

Kalau sudah dipublish ke npm registry, instalnya tinggal:

npm install -g melfic-agent

Di desktop Linux/macOS

npm install -g melfic-agent

Cara kerja dasarnya

Setelah install, ai bisa dipanggil dari folder mana pun, bukan cuma dari folder Melfic sendiri. Workspace yang di-scan/diedit selalu folder tempat kamu menjalankan ai (current directory) — bukan folder instalasi Melfic.

ai                 → mode interaktif di folder ini
ai <instruksi>      → jalankan satu instruksi lalu keluar

Instalasi (npm install -g .) cuma dilakukan sekali, bukan tiap kali mau pakai — beda dengan npm start yang harus dijalankan ulang tiap sesi dan cuma jalan dari dalam folder itu saja.

Setup pertama kali & konfigurasi

Jalankan ai pertama kali, atau ai config kapan saja dari folder mana pun, untuk membuka menu config:

╭──────────────────────────────╮
│       MELFIC CONFIG          │
╰──────────────────────────────╯

Active: gemini/gemini-flash-latest
Gemini key: AIza...8F2x
OpenRouter key: (belum di-set)

1. Gemini
2. OpenRouter
3. Default Model
4. Test Connection
5. Reset Configuration
0. Keluar

Pilih:

• 1 / 2 — masukkan API key Gemini atau OpenRouter kamu.
• 3. Default Model — pilih provider+model yang dipakai ai:
  • Gemini: gemini-flash-latest (cepat/murah, default) atau gemini-pro-latest (reasoning terkuat) — alias resmi Google yang otomatis nunjuk ke model GA terbaru, jadi gak akan basi kalau Google pensiunkan versi lama.
  • OpenRouter: mengambil daftar model asli lalu memisahkan FREE MODELS (harga $0) dari OTHER MODELS, tinggal pilih nomor.
  • Auto: susun daftar rotasi model (boleh campur Gemini + OpenRouter). Kalau model aktif kena rate-limit/quota/error sementara, Melfic otomatis coba model berikutnya di daftar — tapi tidak rotasi kalau errornya API key salah (karena ganti model gak nyelesain itu). Tambah/hapus model di submenu yang sama, lalu pilih "Simpan & aktifkan Auto Mode".
• 4. Test Connection — kirim ping ke model aktif (atau ke semua model di rotasi Auto) dan laporkan hasilnya (berhasil/gagal + alasannya).
• 5. Reset Configuration — hapus semua key & pilihan model, minta konfirmasi dulu.

Shortcut tanpa buka menu:

ai config gemini           # langsung minta API key Gemini
ai config openrouter        # langsung minta API key OpenRouter
ai use gemini
ai use openrouter/<model-id>
ai use auto

Cara Melfic "mikir" (pre-flight scan)

Sebelum mengubah project yang sudah ada, Melfic selalu scan dulu:

🔍 Scanning workspace...

✓ Project type detected: nodejs (express)
✓ Package manager detected: npm
✓ Entry point detected: src/server.js
✓ Architecture: MVC

🧠 Understanding architecture...

Instruksi obrolan biasa ("halo", "apa itu Node.js?") tidak memicu scan ini — cuma instruksi yang berhubungan dengan project (menambah, memperbaiki, mengubah, dst). Setelah scan, Melfic cuma membaca file yang relevan dengan instruksimu (bukan seluruh project — biar hemat token, penting banget kalau pakai API tier gratis), lalu bikin rencana, eksekusi, dan validasi hasilnya pakai script project sendiri (npm test, npm run lint, dst) sebelum bilang berhasil. Melfic mengikuti arsitektur & konvensi project yang sudah ada, bukan maksain gaya sendiri.

Command bawaan

| Command | Fungsi | |---|---| | ai | Mode interaktif di folder saat ini | | ai <instruksi> | Jalankan satu instruksi bahasa natural | | ai scan | Scan struktur/arsitektur lokal (tanpa panggil AI, cepat & gratis) | | ai analyze | Scan + baca file relevan + analisis arsitektur pakai AI | | ai init | Bikin draft AGENTS.md untuk project ini | | ai models | Lihat daftar model yang dikonfigurasi | | ai use gemini / ai use openrouter/<model> / ai use auto | Ganti model aktif | | ai config | Buka menu config (API key, default model, test koneksi, reset) | | ai memory list | Lihat memory jangka panjang yang tersimpan | | ai memory set <key> <value> | Simpan memory jangka panjang | | ai history | Lihat riwayat percakapan di workspace ini | | ai clear | Hapus riwayat percakapan workspace ini | | ai help | Tampilkan bantuan | | ai version | Tampilkan versi |

Mode interaktif & slash command

Jalankan ai tanpa argumen untuk masuk mode interaktif:

Melfic Agent

Workspace: ~/project-kamu

You > 

Command bawaan (scan, analyze, init, models, use, config, memory, history, clear) diproses lokal — gak dikirim ke AI. Selain itu, ada slash command khusus mode interaktif (state-nya per sesi, gak ada di mode one-shot):

| Slash command | Fungsi | |---|---| | /compact | Ringkas percakapan lama jadi 1 pesan (pakai model aktif) biar giliran berikutnya hemat token, pesan-pesan terakhir tetap utuh | | /undo | Batalkan perubahan file terakhir yang dibuat Melfic di sesi ini (buat file → dihapus lagi, edit/timpa → balik ke isi lama, hapus → dikembalikan). Penghapusan folder tidak bisa di-undo otomatis. | | /model | Ganti model cepat tanpa keluar dari REPL | | /tokens | Lihat total pemakaian token (prompt/completion/total) sepanjang sesi ini | | /help | Tampilkan daftar command |

Ketik exit atau quit untuk keluar.

Konvensi project dengan AGENTS.md

Jalankan ai init untuk bikin draft AGENTS.md — standar terbuka lintas-tools (distandarkan Linux Foundation, dibaca native oleh 20+ AI agent termasuk Codex, Cursor, dan Gemini CLI) untuk instruksi tingkat-project: command build/test, konvensi kode, dan batasan ("jangan sentuh folder /legacy", dst).

ai init tidak minta AI yang menulisnya — draft dibuat murni dari hasil scan lokal (tipe project, framework, script terdeteksi, arsitektur), lalu kamu edit manual. Kalau AGENTS.md sudah ada, Melfic otomatis membacanya dan mengikutinya — dengan prioritas tinggi, di atas aturan umum Melfic sendiri — setiap kali ai dijalankan di project itu.

Keamanan

• Batas workspace: semua tool filesystem menolak path apa pun yang keluar dari folder project saat ini (mencegah ../../file dst).
• Preview perubahan file: sebelum Melfic membuat file baru, menimpa, mengedit, atau menghapus file, kamu akan lihat persis apa yang berubah — diff berwarna untuk edit/timpa, preview isi untuk file baru — dan diminta konfirmasi [y/N/a]. a = setuju perubahan ini dan semua perubahan berikutnya untuk sisa instruksi itu (biar bikin 10 file gak nanya 10 kali); reset lagi tiap instruksi baru.
• Konfirmasi command berbahaya: command shell seperti rm -rf, git push --force, git reset --hard, operasi disk-level, dan npm publish butuh konfirmasi y eksplisit sebelum dijalankan.
• API key kamu, urusan kamu: Melfic tidak pernah menyertakan atau mewajibkan API key bersama. Tiap user pakai key sendiri, tidak pernah dikirim ke mana pun selain langsung ke API provider terkait.

Data lokal

Semua tersimpan di ~/.melfic/:

• config.json — pengaturan provider & API key (permission file 0600, tidak pernah dicatat log)
• memory.db — database SQLite (node:sqlite bawaan Node) untuk percakapan, pesan, memory jangka panjang, cache konteks project
• logs/ — log teks biasa, secret sudah disensor
• cache/ — cadangan untuk cache di masa depan

Troubleshooting

"No command ai found" — berarti ai belum terinstall secara global. Kamu mungkin menjalankan CLI-nya secara lokal (npm start, node bin/ai.js) di dalam folder Melfic, bukan install global. Jalankan lagi dari dalam folder Melfic:

cd path/to/melfic-agent
npm install -g .
which ai
ai --version

Kalau which ai masih kosong, folder bin npm global kamu mungkin belum ada di PATH. Cek dengan npm config get prefix, pastikan <path>/bin ada di PATH shell kamu (di Termux biasanya $PREFIX/bin, sudah otomatis ada).

"Permission denied" menjalankan ai — biasanya karena file bin/ai.js kehilangan izin execute (sering terjadi kalau di-extract dari shared storage Android yang tidak mendukung permission Unix). npm install -g . seharusnya otomatis memperbaikinya. Kalau masih macet, paksa install ulang total:

npm uninstall -g melfic-agent
npm install -g .

Arsitektur (untuk kontributor)

bin/ai.js          entrypoint CLI
src/cli/            router, command bawaan, REPL interaktif, slash command
src/agent/           planner (keputusan pre-flight scan) + loop model↔tool, undo stack
src/providers/       interface provider-neutral + adapter Gemini/OpenRouter
src/tools/           tool filesystem, shell, search + schema provider-neutral
src/scanner/         scan project berlapis (struktur → metadata → arsitektur → relevansi)
src/context/         system prompt builder + dukungan AGENTS.md
src/memory/          SQLite: percakapan, pesan, memory, cache project
src/config/          manager ~/.melfic/config.json
src/security/         batas workspace, konfirmasi command berbahaya, diff & konfirmasi perubahan file

Jalankan test suite dengan:

npm test

🇬🇧 English

Melfic Agent is a real agentic coding CLI — not a chatbot. It runs as the ai command, understands the structure and architecture of the project you're standing in, inspects and edits files, runs shell commands, and remembers conversations locally. Built to run comfortably inside Termux on Android, no laptop or root required, and works with Gemini or OpenRouter using your own API keys.

ai buat folder bernama s3raph lalu npm init
ai perbaiki error di project ini
ai tambahkan authentication ke project ini

No quotes needed — everything after ai is treated as one natural-language instruction.

Install

On Termux (Android)

pkg update
pkg install nodejs unzip
termux-setup-storage
cd ~
unzip ~/storage/downloads/melfic-agent.zip -d ~
cd ~/melfic-agent
npm install -g .

No compiler toolchain needed — local memory uses Node's built-in node:sqlite, which requires Node.js 22.5 or newer. Check with node -v; if it's older, run pkg install nodejs again (Termux usually ships a recent version) or try pkg install nodejs-lts.

Once published to the npm registry, install becomes just:

npm install -g melfic-agent

On desktop Linux/macOS

npm install -g melfic-agent

How it works

Once installed, ai can be called from any directory — not just the Melfic source folder. The workspace that gets scanned/edited is always the directory you ran ai from (current working directory), never Melfic's own install location.

ai                 → interactive mode in the current directory
ai <instruction>     → run one instruction then exit

The install step (npm install -g .) only needs to happen once — unlike npm start, which has to be re-run every session and only works from inside that specific folder.

First run & configuration

Run ai for the first time, or ai config any time from anywhere, to open the config menu:

╭──────────────────────────────╮
│       MELFIC CONFIG          │
╰──────────────────────────────╯

Active: gemini/gemini-flash-latest
Gemini key: AIza...8F2x
OpenRouter key: (not set)

1. Gemini
2. OpenRouter
3. Default Model
4. Test Connection
5. Reset Configuration
0. Keluar

Pilih:

• 1 / 2 — paste in your Gemini or OpenRouter API key.
• 3. Default Model — pick which provider+model ai uses:
  • Gemini: gemini-flash-latest (fast/cheap, default) or gemini-pro-latest (strongest reasoning) — Google-maintained aliases that always point at the current GA model, so they won't quietly break when Google retires an older pinned version.
  • OpenRouter: fetches the live model list and splits it into FREE MODELS (priced at $0) and OTHER MODELS, so you can pick a free one by number.
  • Auto: build an ordered rotation of models (mixing Gemini and OpenRouter). If the active model hits a rate limit, quota error, or temporary outage, Melfic automatically tries the next one in the list — it never rotates on an invalid API key, since retrying doesn't fix that. Add/remove entries from the same submenu, then "Simpan & aktifkan Auto Mode" to save and activate.
• 4. Test Connection — pings the active model (or every model in the Auto rotation) and reports success or the exact error.
• 5. Reset Configuration — wipes all keys and model choices (asks for confirmation first).

Scripting shortcuts without the menu:

ai config gemini           # prompts for just the Gemini key
ai config openrouter        # prompts for just the OpenRouter key
ai use gemini
ai use openrouter/<model-id>
ai use auto

How Melfic thinks (pre-flight scan)

Before modifying an existing project, Melfic always scans it first:

🔍 Scanning workspace...

✓ Project type detected: nodejs (express)
✓ Package manager detected: npm
✓ Entry point detected: src/server.js
✓ Architecture: MVC

🧠 Understanding architecture...

Plain conversation ("halo", "what is Node.js?") does not trigger this scan — only instructions that actually relate to the project (adding, fixing, modifying, etc). After scanning, Melfic only reads the files relevant to your instruction (not the whole project — keeping token usage low matters most on free API tiers), plans, executes, and validates its own work using the project's own scripts (npm test, npm run lint, etc.) before reporting success. Melfic follows the project's existing architecture and conventions instead of imposing its own.

Built-in commands

| Command | What it does | |---|---| | ai | Start interactive mode in the current directory | | ai <instruction> | Run one natural-language instruction | | ai scan | Local, deterministic structure/architecture scan (no API calls, fast & free) | | ai analyze | Scan + read relevant files + AI-assisted architecture analysis | | ai init | Generate a starter AGENTS.md for this project | | ai models | List configured models | | ai use gemini / ai use openrouter/<model> / ai use auto | Switch active model | | ai config | Open the config menu (API keys, default model, test connection, reset) | | ai memory list | List stored long-term memories | | ai memory set <key> <value> | Store a long-term memory | | ai history | List past conversations for this workspace | | ai clear | Clear this workspace's conversation history | | ai help | Show help | | ai version | Show version |

Interactive mode & slash commands

Run ai with no argument to enter interactive mode:

Melfic Agent

Workspace: ~/your-project

You > 

Built-in commands (scan, analyze, init, models, use, config, memory, history, clear) are handled locally — never sent to the AI. On top of that, these slash commands only exist in interactive mode (they act on per-session state that a one-shot command doesn't keep around):

| Slash command | What it does | |---|---| | /compact | Summarizes older conversation history into one message (via the active model) to keep future turns cheap, keeping the last few messages verbatim | | /undo | Reverts the most recent file change Melfic made this session (create → delete it, edit/overwrite → restore previous content, delete → restore it). Directory deletions can't be auto-undone. | | /model | Quick model switch without leaving the REPL | | /tokens | Shows cumulative prompt/completion/total token usage for the session | | /help | Shows the command list |

Type exit or quit to leave.

Project conventions with AGENTS.md

Run ai init to generate a starter AGENTS.md — the open, cross-tool standard (Linux Foundation-stewarded, natively read by 20+ agents including Codex, Cursor, and Gemini CLI) for project-level instructions: build/test commands, coding conventions, and boundaries ("never touch /legacy", etc).

ai init never asks an LLM to write it — it builds a draft purely from the local scan (project type, framework, detected scripts, architecture), which you then edit by hand. If AGENTS.md already exists, Melfic reads and follows it — at high priority, above its own general defaults — every time you run ai in that project.

Safety

• Workspace boundary: filesystem tools refuse any path that resolves outside the current project directory (blocks ../../file escapes).
• File change preview: before Melfic writes a new file, overwrites one, edits one, or deletes one, it shows exactly what will change — a colored diff for edits/overwrites, a content preview for new files — and asks [y/N/a] before touching disk. a approves that change and every further one for the rest of that instruction; it resets on your next instruction.
• Dangerous command confirmation: shell commands like rm -rf, git push --force, git reset --hard, disk-level operations, and npm publish require explicit y confirmation before running.
• Your keys, your calls: Melfic never ships or requires a shared API key. Each user configures their own, sent only directly to that provider's API.

Local data

Everything lives under ~/.melfic/:

• config.json — provider settings and API keys (file mode 0600, never logged)
• memory.db — SQLite database (Node's built-in node:sqlite) for conversations, messages, long-term memories, project-context cache
• logs/ — plain-text logs with secrets redacted
• cache/ — reserved for future on-disk caches

Troubleshooting

"No command ai found" — means ai was never installed as a global binary. You likely ran the CLI locally (npm start, node bin/ai.js) inside the Melfic folder instead of installing it globally:

cd path/to/melfic-agent
npm install -g .
which ai
ai --version

If which ai still prints nothing, your global npm bin directory probably isn't on PATH. Check with npm config get prefix and make sure <that path>/bin is on your shell's PATH (on Termux this is normally $PREFIX/bin, already on PATH by default).

"Permission denied" running ai — usually means bin/ai.js lost its executable bit (common when extracted from Android shared storage, which doesn't support Unix permissions). npm install -g . should fix this automatically. If it's still stuck, force a completely clean reinstall:

npm uninstall -g melfic-agent
npm install -g .

Architecture (for contributors)

bin/ai.js            CLI entrypoint
src/cli/               router, built-in commands, interactive REPL, slash commands
src/agent/              planner (pre-flight scan decision) + model↔tool loop, undo stack
src/providers/          provider-neutral interface + Gemini/OpenRouter adapters
src/tools/               filesystem, shell, search tools + provider-neutral schemas
src/scanner/             layered project scanning (structure → metadata → architecture → relevance)
src/context/             system prompt builder + AGENTS.md support
src/memory/              SQLite: conversations, messages, memories, project cache
src/config/              ~/.melfic/config.json manager
src/security/            workspace boundary, dangerous-command confirmation, file-change diff & confirmation

Run the test suite with:

npm test