Lokal

Why Lokal?

Ask an AI agent to "build a checkout form" and you usually get an American one:

The second problem is easy to miss. While debugging, developers paste production logs and customer CSVs into Claude or Cursor, and national ID numbers (NIK), phone numbers, and bank accounts go straight to the model provider. Under Indonesia's personal data protection law, UU PDP (UU 27/2022), that is a real liability.

Lokal fixes both: it teaches agents Indonesian conventions, gives them accurate reference data, and puts Samaran (Indonesian for disguise) between your data and the model.

Features

• Indonesian conventions for agents. Money, phone numbers, NIK/NPWP, tiered addresses, WIB/WITA/WIT, local payment methods, UI copy, and UU PDP, packaged as Agent Skills.
• Accurate reference data, bundled. All 38 provinces down to 83,762 villages, matching the Kemendagri 2025 decree exactly, with postal codes for every village. Public holidays and cuti bersama from the official SKB for 2026 and 2027.
• Samaran masking. Replaces 25 kinds of Indonesian personal data, covering every category in UU PDP Article 4, with stable placeholders, then restores them in the model's output.
• Samaran Guard. A hook for Claude Code, Codex CLI, Cursor, and Gemini CLI that stops prompts containing ID numbers and redirects reads of customer data files (Read, Grep, cat, Get-Content, …) to a masked view.
• Kembaran. Copies production dumps and exports for staging with every person replaced by a realistic stand-in: a valid NIK in the same district, a phone number on the same operator, consistent across tables.
• Samaran Proxy. An OpenAI- and Anthropic-compatible endpoint that masks personal data in every LLM call your app makes and restores it in the answers, streaming included. Change the base URL, not the code.
• Works with any agent. Claude Code plugin, stdio MCP server for Cursor, Claude Desktop, VS Code, Windsurf, and Codex, an HTTP server for ChatGPT and Claude.ai connectors, plus TypeScript and Python libraries with identical results.
• Local and offline. Data ships with the package. No network calls, no telemetry, and unmasking happens on your machine.

How it works

When the agent needs to look at customer data, it calls read_file_masked and sees [NAME_1], [NIK_1], [PHONE_1] instead of the real values. It can still deduplicate, join, and debug, because the same value always gets the same placeholder. When it writes results with write_file_unmasked, Samaran puts the real values back, on your machine.

Quick start

Claude Code

Installs the skills, the MCP server, and Samaran Guard in one step:

/plugin marketplace add lokal-id/lokal
/plugin install lokal@lokal

claude mcp add lokal -- npx -y @lokal-id/mcp

Other MCP clients

{
  "mcpServers": {
    "lokal": {
      "command": "npx",
      "args": ["-y", "@lokal-id/mcp"],
      "env": { "LOKAL_ROOT": "/path/to/your/project" }
    }
  }
}

{
  "servers": {
    "lokal": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@lokal-id/mcp"]
    }
  }
}

[mcp_servers.lokal]
command = "npx"
args = ["-y", "@lokal-id/mcp"]
env = { LOKAL_ROOT = "/path/to/your/project" }

npx @lokal-id/mcp serve --http --port 3000                  # http://127.0.0.1:3000/mcp
npx @lokal-id/mcp serve --http --host 0.0.0.0 --port $PORT  # on a Node host such as Render or Fly.io

The file tools (scan_pii, read_file_masked, write_file_unmasked) can only access LOKAL_ROOT, which defaults to CLAUDE_PROJECT_DIR and then to the directory the server was started in.

Skills only, for any agent

npx skills add lokal-id/lokal

This installs lokal-indonesia and samaran with the skills CLI into Claude Code, Codex, Cursor, and the other agents it supports. Add -g to install them for your user instead of the current project.

Skills teach the agent the conventions. For accurate region, postal code, and holiday data and for masked file reads, add the MCP server as well (see above). Samaran Guard is a hook: it comes with the Claude Code plugin, and can be set up in Codex CLI, Cursor, and Gemini CLI.

You can also copy the folders in skills/ by hand. They use the open Agent Skills format (SKILL.md).

Library

npm install @lokal-id/core     # TypeScript / JavaScript
pip install lokal-id           # Python 3.10+

The Python package is a port of @lokal-id/core with the same rules and data, verified against thousands of TypeScript outputs. It adds Decimal money, date objects, dataclass results, a logging filter for backends, and lokal.files, the MCP server's file readers, to scan an upload folder (scan_pii for your backend) or mask a PDF before it reaches an LLM. See python/.

Usage

Library

import {
  parseNik, parsePhone, formatRupiah, parseRupiah, terbilang, addWorkingDays, isWorkingDay, parseQris, setQrisAmount,
} from '@lokal-id/core';
import { listWilayah, searchWilayah, wilayahName, findByPostalCode } from '@lokal-id/core/wilayah';

parseNik('3201011508950001', { lookupWilayah: wilayahName });
// { valid: true, province: 'Jawa Barat', regency: 'Kabupaten Bogor', district: 'Cibinong',
//   gender: 'L', birthDate: '1995-08-15', … }

parsePhone('0812 3456 7890');
// { e164: '+6281234567890', national: '0812-3456-7890', whatsapp: '6281234567890', operator: 'Telkomsel', … }

formatRupiah(1500000);                   // 'Rp1.500.000'
terbilang(1500000, { currency: true });  // 'satu juta lima ratus ribu rupiah'
parseRupiah('2jtan');                    // { amount: 2000000, approximate: true }
parseRupiah('sejuta setengah');          // { amount: 1500000, approximate: false }

listWilayah('32.76');                    // districts (kecamatan) of Kota Depok
searchWilayah('kab. bogor')[0].code;     // '32.01'
findByPostalCode('16431');               // villages that use this postal code

addWorkingDays('2026-03-17', 1);         // '2026-03-25', skipping Nyepi and Lebaran
isWorkingDay('2026-12-24', { cutiBersama: false }); // true for offices that ignore cuti bersama

parseQris(payload);                      // { valid, type: 'static', merchantName, nmid, criteriaLabel: 'Usaha Mikro', … }
setQrisAmount(payload, 25000);           // the same merchant's QRIS, dynamic, for Rp25.000, with a new CRC

@lokal-id/core/wilayah loads about 4.4 MB of region data and runs on Node only. The main entry point does not load it and is safe for browsers.

Samaran: mask before the LLM, restore after

import { Samaran } from '@lokal-id/core';

const samaran = new Samaran();

const { text } = samaran.mask(
  'Nama: Budi Santoso, NIK 3201011508950001, refund ke rek BCA 1234567890, HP 0812-3456-7890',
);
// 'Nama: [NAME_1], NIK [NIK_1], refund ke rek BCA [BANK_ACCOUNT_1], HP [PHONE_1]'

const reply = await llm(text);   // the model never sees the real values
samaran.unmask(reply);           // placeholders are replaced with the original data

• The same value always maps to the same placeholder, across formats: 0812-… and +62 812… are both [PHONE_1].
• mode: 'partial' is meant for logs and admin screens: 3201********0001, 0812****7890, b***@gmail.com.
• exclude keeps types your app has to read. A car dealer's credit simulation needs income and installments, so new Samaran({ exclude: ['FINANCIAL'] }) leaves "gaji saya 8 juta, cicilan 3 juta" intact while NIK and phone numbers are still masked. A misspelled type name throws instead of silently masking less.
• Detection uses labels (Agama: Islam, NAMA : BUDI), CSV and Excel headers (agama, diagnosa, gaji, …), JSON/YAML keys and query strings (including split first_name / last_name), SQL INSERT dumps, WhatsApp chat exports, and common phrases in free text (nama saya budi, didiagnosis TBC, obat insulin, gaji saya 8 juta).

Samaran Proxy: protect an app's LLM calls

Masking by hand means every call site has to remember it. The proxy does it for the whole app: start it next to your backend and point the SDK's base URL at it.

npx @lokal-id/mcp proxy                 # http://127.0.0.1:8787

from openai import OpenAI
from anthropic import Anthropic

client = OpenAI(base_url='http://127.0.0.1:8787/v1')   # Chat Completions, Responses, embeddings
claude = Anthropic(base_url='http://127.0.0.1:8787')   # Messages

• Every text in the request is masked before it leaves your server: the conversation history, system prompts, tool results, and tool call arguments. Images, IDs, and signed thinking blocks are left alone.
• Responses come back with the real values, streamed or not, including tool call arguments, so the tools your app runs get real data.
• Each request gets its own vault. Masking the whole conversation in order gives the same person the same placeholder on every turn.
• Other OpenAI-compatible APIs work too: --openai https://openrouter.ai/api/v1, Groq, DeepSeek, Ollama, or Gemini's OpenAI endpoint. --exclude FINANCIAL lets the model see income figures for a credit simulation.
• It listens on 127.0.0.1 only, passes API keys through without storing them, and logs one line per request with counts, never values. Each response has an x-samaran-masked: NIK=1,NAME=2 header. File uploads cannot be masked and are refused unless you start it with --allow-unmasked.

Tested end to end with Claude Code itself running through it: the model only ever saw placeholders, and the files it wrote with its tools had the real values.

Kembaran: production data for staging, without real people

Copying production data to staging or a laptop is the most common way personal data leaks. Kembaran makes a copy in which every person is a realistic stand-in, so the data still behaves like production:

npx @lokal-id/mcp kembaran prod.sql export.csv -o staging/ --secret staging-2026
python -m lokal.kembaran prod.sql -o staging.sql          # the same, from a Python backend

nama,nik,tgl_lahir,hp,email
Budi Santoso,3201011508950001,15-08-1995,0812-3456-7890,budi.santoso@gmail.com
↓
Slamet Matondang,3201012409953895,24-09-1995,0812-8655-8077,rini.pertiwi10@example.com

• The same value gets the same stand-in in every file of one run, so joins and foreign keys hold. 0812-3456-7890 and +62 812 3456 7890 are one person. An individual's NPWP stays equal to their NIK.
• Stand-ins come from HMAC-SHA256 under a secret. Without --secret it is random for each run; with one, a weekly staging refresh gives the same people. NIKs, phone numbers, and account numbers never collide.
• Gender, religion, marital status, and nationality are kept by default; --keep FINANCIAL keeps more. --keep-birth-date keeps whole birth dates.
• In an agent, the anonymize_file tool does it on your machine and returns only counts. TypeScript: new Kembaran({ secret }).text(text) from @lokal-id/core/kembaran; Python: Kembaran(secret=…).text(text) from lokal.kembaran, with the same output for the same secret.

A stand-in phone number can still belong to someone, so keep staging from sending SMS or WhatsApp. Text files only (SQL dumps, CSV, JSON, logs) up to 100 MB; about 2 MB/s in TypeScript.

MCP tools

Samaran Guard

Enabled automatically by the Claude Code plugin.

• Prompts containing ID numbers (NIK, KK, NPWP, passport, SIM, NIP, bank account, BPJS, card) or labeled health, criminal, or biometric data are held before they are sent. Add #izinkan-pii to send anyway.

• Reads of data files (CSV, Excel, JSON, logs, SQL dumps, YAML, …) that contain personal data are blocked, and Claude is pointed to read_file_masked. This covers the Read tool, Grep in content mode, and shell commands such as cat, head, grep, sed -n, awk, cut, Get-Content, and Import-Csv | Select-Object.

• Photos and PDFs Samaran cannot read are asked about first. Read sends images and PDFs to the model as they are. For a photo named or filed like someone's document (ktp-budi.jpg, selfie_siti.png, anything under media/, uploads/, or storage/ except the app's own assets/ and images/) and for a scanned, encrypted, or damaged PDF, Claude Code shows a permission prompt with the reason. A PDF whose text contains personal data is blocked as a data file.

• Only what would be printed counts. head -1 data.csv (the header), wc -l, grep -c, and sort data.csv > out.csv still run.

• Not blocked: source code, where sample numbers are normal and the agent must be able to read them, and scripts run on data files (node process.js data.csv), which is how data gets processed without being shown to the model.

• List files that contain fake data (fixtures, seeders) in .samaranignore:

  test/fixtures/
  database/seeders/
  *.example.csv
  

• Set SAMARAN_GUARD=off to disable the guard.

In Codex CLI, Cursor, and Gemini CLI

The same guard works as a hook in other agents: lokal-mcp guard recognizes each agent's events and answers in its format. Install it once so the hook starts fast (npx on every file read is slow):

npm install -g @lokal-id/mcp

{
  "hooks": {
    "UserPromptSubmit": [{ "hooks": [{ "type": "command", "command": "lokal-mcp guard" }] }],
    "PreToolUse": [{ "matcher": "Bash", "hooks": [{ "type": "command", "command": "lokal-mcp guard" }] }]
  }
}

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [{ "command": "lokal-mcp guard" }],
    "beforeReadFile": [{ "command": "lokal-mcp guard" }],
    "beforeShellExecution": [{ "command": "lokal-mcp guard" }]
  }
}

{
  "hooks": {
    "BeforeAgent": [{ "hooks": [{ "type": "command", "command": "lokal-mcp guard" }] }],
    "BeforeTool": [{ "matcher": "read_file|run_shell_command", "hooks": [{ "type": "command", "command": "lokal-mcp guard" }] }]
  }
}

Evaluation

The same vibe-coding tasks were run in real Claude Code sessions in an empty folder, with and without the Lokal plugin, three times each (npm run eval, cases in evals/cases.mjs):

A fifth task, debugging an app.log that contains customer NIK, phone numbers, and emails, was added later. Without Lokal, the agent ran Get-Content app.log and the whole log reached the model. With Lokal, the agent used scan_pii → read_file_masked, and no customer data reached the model in 2 of 2 runs. The first run of this task exposed a bug where a key=value log field swallowed the next pair and leaked a phone number through the scan preview. It is fixed and covered by a regression test.

Hard cases

Three harder tasks use answers checked against official sources rather than Lokal's own data, and real document formats with fake identities (2 runs each):

The first runs of these tasks found a bug and four detection gaps, all fixed in 0.2.1: a phone number at the end of a line leaked when the next line began with a digit, and names split into first_name / last_name, WhatsApp senders, medicines and hospital stays were missed. The id.wikipedia list of Depok postal codes turned out to be wrong for 32 kelurahan; Lokal matches en.wikipedia and other sources.

npm run eval:pii runs the format benchmark on its own: 43 of 43 personal values masked across 15 formats (KTP OCR, WhatsApp exports, Midtrans JSON, Laravel logs, SQL dumps, …), and 27 of 27 look-alikes left intact (resi numbers, invoice IDs, timestamps, call-center numbers, institutions).

This is a small sample built around everyday tasks for Indonesian developers. Do not read it as a general benchmark.

Limitations

• Detection is pattern-based and favors precision. Names are found through labels, column headers and JSON keys, chat export senders, introductions ("nama saya budi", "atas nama", "a.n.", "halo kak ini rina,"), honorifics ("Pak Joko", "bapak ahmad"), and reported speech ("tadi budi bilang"), including lowercase. A name dropped into a sentence with no cue at all ("pesanan budi belum sampai"), unusually phrased health or financial data, and children's data that is not marked as such can still slip through. Treat Samaran as a strong safety net, not a guarantee.
• Tested for false positives on 12 MB of open-source code and the full text of UU 27/2022, with no high-confidence name detections. Chat name detection caught 29 of 29 test sentences with names and flagged 0 of 26 ordinary chat sentences. The sentences were written for the test suite, so accuracy on real chats may be lower.
• Not every format is read. PDFs are read when they have a text layer, as invoices, letters, statements, and forms from a browser, Word, or a PDF library do. Scanned pages, encrypted PDFs, legacy .xls and .doc, images (ID card photos, selfies), and archives are not scanned. scan_pii reports them as not scanned, never as clean, including scanned pages inside an otherwise readable PDF. The guard asks before Read sends such a PDF, or a photo that looks like someone's document, to the model; it cannot tell a KTP photo from any other picture, so it judges photos by name and folder. Files over 100 MB are reported too. For data files over 5 MB the guard checks the first 5 MB, and it reports spreadsheets, Word documents, and PDFs over 20 MB instead of parsing them, to stay within the hook's 10-second limit.
• NIK and NPWP checks are structural. They cannot confirm that a number is registered with Dukcapil or the tax office.
• Carrier detection uses number prefixes, which match the public allocation list, including the 2025 XLSmart merger. Indonesia has no mobile number portability yet (a case is pending at the Constitutional Court, 319/PUU-XXIV/2026), so prefixes are still reliable. Landline area codes cover 19 major cities.
• The guard intercepts prompts, Read, Grep, and common shell readers. A script that deliberately prints a data file, or something like python -c "print(open(...).read())", cannot be caught every time. The samaran skill steers the agent away from that.
• Holidays exist only for years whose SKB has been published (2026, 2027). Other years return an error, not a guess.

Roadmap

• National holidays and cuti bersama per year
• Postal codes for every village
• UU PDP data categories and Excel support in Samaran
• Kapan: Indonesian time expressions (besok abis maghrib, lusa jam 7an, tanggal muda) with location-based prayer times
• Warga: consistent synthetic test data (NIK matching birth date and region, region-appropriate names)
• .docx support in Samaran (text and tables)
• Text-based PDF support in Samaran (page text, tables, form fields)
• OCR for scanned PDFs and ID card photos
• Free-text address parser → region codes
• HTTP transport for ChatGPT and web-based agents
• Python library (lokal-id) with the same results as TypeScript
• Locale packs for other countries (Malaysia, the Philippines, Vietnam)

Have an idea? Open an issue.

Project structure

packages/core     @lokal-id/core: logic and bundled data
packages/mcp      @lokal-id/mcp: MCP server and Samaran Guard
python/           lokal-id: the Python port, with parity tests against TypeScript
skills/           SKILL.md files for Claude, Codex, and other agents
hooks/            Claude Code hook (bundled, no dependencies)
evals/            end-to-end evaluation against real Claude Code sessions
.claude-plugin/   plugin and marketplace manifests

Contributing

Contributions are welcome, in English or Bahasa Indonesia. Missed detections and false positives are especially useful. See CONTRIBUTING.md for setup and guidelines, and never include real personal data in issues or pull requests.

npm install
npm run build   # core, mcp, and the bundled hook
npm test        # unit tests, MCP server end to end, guard
npm run eval    # real Claude Code sessions with and without the plugin

Security

If you find a way to get personal data past Samaran or the guard, please report it privately as described in SECURITY.md rather than opening a public issue.

Releases are built from a tag by GitHub Actions and published with Trusted Publishing and provenance. @lokal-id/core and the Python package have no dependencies, and @lokal-id/mcp bundles its own, so installing Lokal pulls in no third-party packages. SECURITY.md describes how releases are protected and how to verify what you installed.

License

Code is released under the MIT License. Bundled data keeps its own terms:

Region totals match the Kemendagri decree exactly and were last checked in October 2026; see packages/core/data/README.md to regenerate them. Every holiday date is tested against the weekday in the official announcement. The UU PDP summary in the skills was checked against the official text of UU 27/2022.

Acknowledgements

• cahyadsn for maintaining open Indonesian region and postal code data.
• Model Context Protocol and Agent Skills for open standards that let one toolkit work across agents.