DOCSEARCHbyAlgolia
Submit Docs

shinkoku

repository·main·Indexed 43 days ago

https://github.com/kazukinagata/shinkoku

An AI coding agent plugin and CLI tool designed to automate Japanese tax filings for Income Tax and Consumption Tax. It supports end-to-end workflows including bookkeeping, financial statement generation, OCR reading of receipts and withholding slips, and automated data entry into the e-Tax portal. Compatible with Claude Code, Cursor, Windsurf, GitHub Copilot, and other AI agents via the skills CLI.

Tokens
194.7K
Snippets
360
Records
826
Agent score
54%

What's inside shinkoku

  1. Overview of Income Deductions (令和7年/2025)

    main

    Income deductions are used to subtract specific amounts from your total income to calculate your taxable income (based on Income Tax Act Articles 72–86). For the 2025 tax year (令和7年分), there are 14 standard deductions plus the Basic Deduction (基礎控除).

    Key Deductions Summary

    #Deduction NameMax AmountTarget/Condition
    1Casualty Loss (雑損控除)No limitLoss due to disaster, theft, or embezzlement
    2Medical Expense (医療費控除)2 million JPYOut-of-pocket medical expenses
    3Social Insurance (社会保険料控除)Full amountHealth insurance, pension, etc.
    4Small Enterprise Mutual Aid (小規模企業共済等掛金控除)Full amountiDeCo, Small Enterprise Mutual Aid premiums
    5Life Insurance (生命保険料控除)120,000 JPYLife, long-term care, or individual annuity insurance
    6Earthquake Insurance (地震保険料控除)50,000 JPYEarthquake insurance premiums
    7Donation (寄附金控除)40% of income - 2,000 JPYFurusato Nozei, specific donations
    8Disability (障害者控除)270k/400k/750k JPYSelf, spouse, or dependents with disabilities
    9Widow (寡婦控除)270,000 JPYQualifying widows
    10Single Parent (ひとり親控除)350,000 JPYQualifying single parents
    11Working Student (勤労学生控除)270,000 JPYQualifying students
    12Spouse (配偶者控除)380k/480k JPYSpouse with income below a certain threshold
    13Special Spouse (配偶者特別控除)380,000 JPYGraduated deduction for those ineligible for Spouse Deduction
    14Dependent (扶養控除)380k–630k JPYHaving qualifying dependents
    —Basic Deduction (基礎控除)Max 950,000 JPYEveryone (if total income ≤ 25 million JPY)

  2. Overview of the shinkoku CLI system

    main

    The shinkoku CLI is an automated tax filing support system designed for sole proprietors and employees to manage bookkeeping and calculate income and consumption taxes.

    Core Capabilities:

    • Double-entry bookkeeping (Journals, General Ledgers, Trial Balances, P&L, Balance Sheets).
    • Income tax calculation (Business, Salary, Miscellaneous income).
    • Consumption tax calculation (Special rule for 20%, Simplified tax, Standard tax).
    • Various deduction calculations (Blue return, Life insurance, Medical expenses, etc.).
    • Data ingestion via CSV, Receipt OCR, and Invoice OCR.

    Technical Environment:

    • Runtime: Python 3.11 or higher.
    • Database: SQLite (running in WAL mode).
    • Interface: CLI via the shinkoku command.
    • Data I/O: JSON format via stdin/stdout.

  3. Manage Furusato Nozei donations with `/furusato`

    main

    The /furusato skill allows you to manage Furusato Nozei (hometown tax donation) data by reading donation certificates, registering donation details, and calculating tax deductions.

    Key Capabilities:

    • OCR Processing: Read donation certificates from images (requires a Vision-capable multimodal LLM).
    • Batch Processing: Handle multiple certificates at once.
    • Data Registration: Record municipality name, amount, donation date, and whether the One-Stop Special Provision (ワンストップ特例) applies.
    • Aggregation: View lists of registered donations and calculate total amounts and deduction amounts (Total - 2,000 JPY).
    • Estimation: Estimate deduction upper limits if income information is provided and warn if limits are exceeded.
    • Guidance: Provides information regarding the relationship between the One-Stop Special Provision and final tax returns.

    Workflow Integration: Run this skill before performing income tax calculations (/income-tax) so that donation deductions are automatically reflected in your tax return.

    /furusato

  4. Project structure and Agent Skills

    main

    The project is organized into several key directories:

    • .claude-plugin/: Contains the plugin.json manifest for Claude Code.
    • skills/: Contains Agent Skills following the SKILL.md open standard. Each skill handles a specific domain (e.g., assess/SKILL.md for tax necessity determination, reading-receipt/SKILL.md for OCR).
    • src/shinkoku/: The core source code.
      • cli/: CLI entry points (the shinkoku command) including subcommands for ledger management, tax calculation, and data import.
      • tools/: Pure business logic functions.
      • models.py: Pydantic model definitions.
      • db.py: SQLite database management.
    • tests/: Test suites (unit, scripts, integration, fixtures, helpers).
    • shinkoku.config.example.yaml: A template for the project configuration file.

  5. Manage Furusato Nozei (Hometown Tax) donations

    main

    The furusato skill manages hometown tax donations by reading donation receipts, registering donation data, and calculating deduction limits. It automates the process of extracting data from images and managing records for tax filing.

    Trigger phrases:

    • ふるさと納税 (Furusato Nozei)
    • furusato
    • 寄附金 (Donation)
    • 寄付金 (Donation)
    • ふるさと納税の控除 (Furusato Nozei deduction)
    • 寄附金受領証明書 (Donation receipt)
    • ワンストップ特例 (One-stop special exception)

  6. Use the Journal Entry & Ledger Management skill

    main

    The journal skill is used for bookkeeping tasks including recording journal entries (仕訳), importing transaction data from CSVs, receipts, or invoices, and managing the general ledger. It supports searching, modifying, and deleting entries.

    Core CLI Tools used by this skill:

    • Ledger Management: shinkoku ledger <subcommand> [args]
    • Data Import: shinkoku import <subcommand> [args]

    Note: All commands output JSON to stdout. Inputs are provided via command-line arguments or the --input <json_file> flag.

  7. Overview of the New NISA System

    main

    The New NISA (Nippon Individual Savings Account) system, introduced in January 2024, provides tax-exempt status for investment gains. It consists of two main components that can be used simultaneously.

    Key Specifications

    ItemTsumitate Investment Limit (つみたて投資枠)Growth Investment Limit (成長投資枠)
    Annual Investment Limit1.2 million yen2.4 million yen
    Total Annual Limit3.6 million yen (combined)
    Lifetime Tax-Exempt Limit18 million yen (managed via book value/cost basis)
    Growth Limit within Lifetime—12 million yen
    Tax-Exempt PeriodIndefiniteIndefinite
    Eligible ProductsInvestment trusts suitable for long-term, diversified investingListed stocks, investment trusts, etc.

    Managing the Lifetime Tax-Exempt Limit

    • The 18 million yen limit is managed using the book value (purchase price), not the current market value.
    • If you sell assets, the book value of the sold portion is added back to your available lifetime limit in the following year.
    • Note: You cannot exceed the total annual investment limit (3.6 million yen) even if you have lifetime limit availability.
    Example of limit reuse:
  Year 7: Purchase 1.2m (Tsumitate) + 2.4m (Growth) = 3.6m total
  Year 8: Sell 1.0m worth of Growth assets
  Year 9 onwards: The 1.0m book value limit is restored (subject to the 3.6m annual limit)

  8. Overview of Crypto Asset Taxation

    main

    Profits generated from the sale, exchange, or use of crypto assets are generally classified as Miscellaneous Income (雑所得) and are subject to Aggregate Taxation (総合課税).

    Key tax characteristics:

    • Income Classification: Primarily Miscellaneous Income (Other).
    • Taxation Method: Aggregate Taxation.
    • Maximum Tax Rate: 55% (45% Income Tax + 10% Resident Tax).
    • Loss Offsetting: Only possible within the Miscellaneous Income category; cannot be offset against other income types.
    • Loss Carryover: Not permitted.

  9. Overview of Housing Loan Tax Credit (住宅ローン控除)

    main

    The Housing Loan Tax Credit (正式名称: 住宅借入金等特別控除) allows for a direct deduction from income tax based on 0.7% of the year-end loan balance.

    Key Specifications

    • Deduction Rate: 0.7% of the year-end balance.
    • Deduction Period:
      • New construction: 13 years.
      • Existing (used) homes: 10 years (increases to 13 years for certified/ZEH/energy-efficient compliant existing homes entering occupancy after Reiwa 8).
    • Application Process:
      • First Year: Requires a Final Tax Return (確定申告). It cannot be handled via year-end adjustment (年末調整).
      • Second Year onwards: Can be applied via Year-end Adjustment (年末調整) at your workplace.

  10. Perform a Cost-Benefit Analysis for Invoice Registration

    main

    To decide whether to register, compare the estimated annual costs against the risks of not registering.

    Costs of Registration (Annual Estimate)

    • A. Consumption Tax Payment:
      • 2-percent rule (2割特例): Sales Tax × 20% (Available until R8).
      • 3-percent rule (3割特例): Sales Tax × 30% (Available R9-R10, individuals only).
      • Simplified Taxation (簡易課税): Sales Tax × (1 - Deemed Purchase Rate).
    • B. Administrative Burden: Costs for issuing/storing invoices, preparing tax returns, and additional accountant fees.

    Risks of Not Registering

    • C. Impact on Client's Input Tax Credit:
      • During transitional periods (e.g., R7: 80% deduction allowed).
      • After full transition (R11.10~): Clients cannot claim any deduction, bearing the full tax burden.
    • D. Business Relationship Impact: Requests for price reductions, loss of clients to registered competitors, or loss of new opportunities.

    Decision Rule:

    • If A < (C + D), registration is recommended.
    • If A > (C + D), staying unregistered may be an option (especially for B2C-focused businesses).

  11. Understand the Salary Income Withholding Tax Slip Input (SS-CA-010)

    main

    The SS-CA-010 screen is used to input data from a physical Salary Income Withholding Tax Slip (給与所得の源泉徴収票). The system uses two distinct form types based on whether Year-End Adjustment (年末調整) has been completed:

    1. Year-End Adjustment Completed (年末調整済み): Uses labels A through L (12 items). This form includes detailed fields for insurance deductions and payer information.
    2. Year-End Adjustment Not Completed (年末調整未済): Uses labels A through E (5 items). This form is more streamlined and includes a field for the total amount of income deductions.

    Navigation Flow: SS-AA-050 (Income/Deduction Hub) → SS-CC-010 (Withholding Slip List) → SS-CA-010 (Input Form)

  12. Identify the 10 types of Income (所得)

    main

    Under the Income Tax Act, income is classified into 10 distinct categories. Use this to determine the correct calculation method for a user's specific financial situation.

    #CategorySummaryCalculation MethodExample
    1Interest (利子所得)Interest from deposits/bondsIncome = Profit
    2Dividend (配当所得)Stock dividendsIncome − Debt interest used for acquisition
    3Real Estate (不動産所得)Rental incomeGross Income − Necessary Expenses
    4Business (事業所得)Income from business/freelancingGross Income − Necessary Expenses
    5Salary (給与所得)Salary and bonusesIncome − Salary Income Deduction
    6Retirement (退職所得)Retirement allowances(Income − Retirement Deduction) × 1/2
    7Forest (山林所得)Logging/forest transfersGross Income − Expenses − Special Deduction
    8Capital Gains (譲渡所得)Asset transfersGross Income − Acquisition Cost − Transfer Expenses − Special Deduction
    9Occasional (一時所得)Temporary incomeGross Income − Expenses − Special Deduction (500k)
    10Miscellaneous (雑所得)Other income (pensions, crypto, side jobs)Gross Income − Necessary Expenses