shinkoku plugin
A Claude Code plugin for Japanese annual tax returns: from bookkeeping to filling in the filing portal, for sole proprietors and employees, in Japanese
- 370 ★ on the repository
- Last commit
- MIT
Broad access
Why this level
- Works with personal data: the individual number, address, phone and financial journal entries stored in the settings file and the SQLite database
- Enters data into the tax return portal through browser automation under your own account
- Errors in calculations and return items can lead to incorrect tax reporting, so you must verify the outcome yourself
Install
- Works in
In your terminal, with SkillFoxx CLI
npx skillfoxx add plugins/shinkokuDetects the agents on your machine, shows the access level and pins the version.
Other ways to install
Access and checks
How we reviewBroad accessThe tool can change data, run commands or handle secrets.
- Works with personal data: the individual number, address, phone and financial journal entries stored in the settings file and the SQLite database
- Enters data into the tax return portal through browser automation under your own account
- Errors in calculations and return items can lead to incorrect tax reporting, so you must verify the outcome yourself
This is third-party code. Review the repository files before installing.
What it does
shinkoku is a Claude Code plugin and a set of skills under the open SKILL.md standard that helps file an annual tax return in Japan. It covers income tax and consumption tax for sole proprietors on the blue return, employees with side income and salary-only workers. The description and interface are in Japanese. The workflow is a chain of skills. `/setup` creates a settings file and a SQLite database, `/assess` decides whether a return is needed and `/gather` lists the documents. `/journal` imports CSVs, receipts, invoices and withholding slips and keeps double-entry records, while `/settlement` computes depreciation and builds a trial balance, profit and loss statement and balance sheet. Then `/income-tax` calculates income tax with deductions and the reconstruction tax, `/consumption-tax` handles consumption tax under three regimes (the 20 percent special rule, simplified and ordinary), and `/submit` leads to filing through e-Tax, by post or in person. The `/e-tax` skill enters data into the filing portal through browser automation: Claude in Chrome, the Antigravity Browser Sub-Agent or Playwright CLI in beta. The `/reading-*` skills read receipts, withholding slips, invoices, deduction certificates and payment statements, and a dual-check mode with two sub-agents cross-verifies the results. Calculations are done by the shinkoku Python program rather than the model. There is also a tax advisor, tracking of furusato nozei donations and a comparison for incorporating. Tax years 2025 and 2026 are covered.
Who it is for. For tax residents of Japan: sole proprietors on the blue return, employees with side income and salaried workers who are ready to check the result themselves and read Japanese.
Good fit when
- You are a sole proprietor in Japan who wants double-entry books plus a trial balance, profit and loss statement and balance sheet
- You need to find out whether you must file income tax and consumption tax returns this year
- You have receipts, invoices and withholding slips and want the agent to read them and enter journal entries
- You need to calculate consumption tax under the 20 percent special rule, the simplified rule or the ordinary rule
- You want to enter data into the filing portal through browser automation and check the totals before submitting
Not a fit when
- You are a stock investor under separate taxation, an FX trader or a real estate owner: these cases are on the unsupported list
- You file the white return or you are a non-resident: only the blue return for Japanese tax residents is supported
- You are unsure about tax matters and want to lean on a machine: the author asks you to verify the result and recommends consulting a tax professional
- You do not read Japanese: the description, skills and the portal interface are in Japanese
Example request
/setup prepare a working folder for my tax return, then tell me which documents I need to collectLimitations
- Python 3.11 or newer and the uv package manager are needed. The skills call the shinkoku utility internally; `/setup` usually installs it, and by hand it is `uv tool install git+https://github.com/kazukinagata/shinkoku`.
- Image reading works only with multimodal models; with text-only models you enter data by hand.
- Entering data into the portal needs browser automation: Claude in Chrome with the `claude --chrome` flag, Antigravity or Playwright CLI in beta.
- Not supported: separate taxation of stocks, FX, real estate income, retirement income, income from selling property, the foreign tax credit, farming and forestry income, the white return and non-residents.
- Taxes change every year: the plugin targets 2025 and 2026, and some later-year rules are only noted as constants without calculation.
- The author asks you to verify all data and totals yourself and accepts no responsibility for losses.
How to disable. Disable or remove the plugin with the Claude Code plugin manager commands, and delete skills installed through npx skills from the agent's skills directory. Your tax working folder stays: it holds shinkoku.config.yaml with personal data, the shinkoku.db database and the .shinkoku and output folders. Delete them yourself when the data is no longer needed.
FAQ
How do I install shinkoku in Claude Code?
Run /plugin marketplace add kazukinagata/shinkoku and /plugin install shinkoku@shinkoku. Python 3.11 or newer and uv are needed. Then create an empty working folder and enter /setup there. For 40 or more other agents there is npx skills add kazukinagata/shinkoku, but without the plugin's image reading.
Who is shinkoku for?
Sole proprietors on the blue return, employees with side income, salary-only workers, consumption tax payers, furusato nozei donors and those who report crypto income as miscellaneous income. Separately taxed stocks, FX, real estate, the white return and non-residents are not supported.
Where does shinkoku keep personal data?
In the working folder: shinkoku.config.yaml with the individual number, address and phone, the shinkoku.db database with journal entries, the .shinkoku folder with a summary and the output folder with reports. In a git repository `/setup` adds them to .gitignore, but a forced git add -f would still commit the data.
How does shinkoku enter data into the filing portal?
The /e-tax skill uses browser automation: Claude in Chrome with the claude --chrome flag (recommended), the Antigravity Browser Sub-Agent or Playwright CLI in beta for WSL and Linux. Filing still goes through e-Tax, by post or in person, and the user checks the totals.
Who calculates the taxes, the model or a program?
The shinkoku Python utility does the calculations with the tax year's constants, and the model only calls it. Receipts and slips are read by a multimodal model, and dual verification with two sub-agents cross-checks results where the agent supports parallel sub-agents.
Discussion
No questions or reviews yet.
Related
PluginsAn open US federal tax engine in a single binary: a CLI and Claude Code skills that prepare and review Form 1040 returns.
A Claude Code skill for personal finance and tax by seven countries rules with statement import and FIRE, all local.
A skill to file an Indian income tax return from the terminal: a deterministic tax engine, both regimes, AY 2026-27
Claude plugin for reading investor filings, sizing portfolio positions and preparing orders for a separate brokerage connector
16 Claude Code commands for Russian sole proprietors: invoices, acts, contracts, taxes and contributions, with data kept in local files
Claude for Financial Services CN
claude-for-financial-services-cn
An unofficial set of 63 skills for Claude Code: DCF, comps, LBO, notes and decks for Chinese equities with Wind, iFind and AkShare data
Comparison with similar tools
Cards that share the main search query, and how they differ.
| Tool | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| shinkoku (this card) | no | 370 | ||
| freee-mcp | yes | OAuth | 518 | the official MCP server of the freee platform: accounting and payroll, with no tax return or portal entry |
| atomno-mcp-fns-calc | no | not required | 1 | an offline Russian tax calculator for an agent that keeps no books and files no return |
README in short
The README, in Japanese, presents the plugin, tables of supported and unsupported cases and a detailed disclaimer. It then covers installation, preparing a working folder, protecting personal data, lists of the main, auxiliary and reading skills, a table of agents with dual verification, a developer section and the technology stack.