kazukinagata/shinkoku

What it solves

This project automates the annual Japanese tax filing process (確定申告) for individuals and small business owners. It removes tedious manual steps: recording transactions in a ledger, calculating income and consumption tax, preparing financial statements, and even filling out the official e-Tax forms. It targets Japanese residents who file taxes as sole proprietors, employees with side income, freelancers, and others.

How it works

Shinkoku is a set of AI-agent skills and a CLI that works with popular AI coding agents like Claude Code, Cursor, and Copilot. After installation, users run slash commands such as /setup, /journal, /income-tax, /consumption-tax, and /e-tax. The tool stores financial data in a local SQLite database, reads tax rules from a Python library, and uses OCR to read receipts and withholding slips. For e-Tax submission, it automates browser entry via Claude in Chrome, Playwright, or Antigravity. The /tax-advisor skill answers tax questions using the LLM, and /furusato handles furusato tax donations. It supports multiple tax schemes (blue form, simplified consumption tax, etc.) and warns about unsupported cases like stock trading or real estate.

Who it's for

Japanese residents who need to file income or consumption tax, including sole proprietors, employees with side income, and those with medical deductions or furusato donations. It is not for non-residents, white-form filers, or those with complex income like stocks, real estate, or foreign tax credits. Users must be comfortable using AI coding agents and must verify all outputs before submission, as the tool explicitly disclaims liability.

Highlights

• End-to-end automation from bookkeeping to e-Tax form filling
• Works with 40+ AI coding agents via the SKILL.md standard
• OCR-based reading of receipts, withholding slips, invoices, and certificates
• Double-check feature using two subagents for OCR verification
• Supports income tax, consumption tax (2% special rule, simplified, standard), furusato donations, and mortgage deductions
• Clear disclaimer that tax filing is the user's responsibility