luopan (罗盘): an industry and company research router for Claude Code and Codex

The problem luopan solves: a question, not a dataset

Most research tooling answers the wrong half of the question. A screener tells you NVIDIA trades at some multiple; it does not tell you whether that multiple leaves room for error. A company wiki tells you ByteDance has many business lines; it does not tell you whether the team you would join owns anything you can later point to. luopan is built around the second half. The README states the intent plainly: "不输出百科，输出判断", output judgement rather than an encyclopedia entry.

The audience is narrow and specific. It is for people who already run an agent such as Claude Code or Codex and want a structured research method loaded into it. The repository topics list career-research, company-research, industry-research, investment-research and skill, which is an accurate description of the scope. It is not a stock app, not a screener, and not a news feed. If your question is "what is the price right now", this is the wrong tool and the README does not pretend otherwise.

How the router works: one entry point, three judgement lines

The root SKILL.md is a dispatcher, not a method. According to the README, it decides whether the subject is an industry or a company, then loads the matching sub-skill from modes/industry/SKILL.md or modes/company/SKILL.md. The repository layout matches that description: a root SKILL.md, a modes/ directory, an agents/ directory, plus review-output/ and test-output/ holding finished reports.

The company branch adds a second fork. If the user has not said why they are researching the company, the router pauses and asks once: investment first, job hunting first, or both. The README is explicit that during that pause it does not search, does not fetch, and does not generate a report. That is the most defensible design decision in the project. An investor needs cash flow, moat and margin of safety; a candidate needs business position, team stability and transferable results. Merging them produces a report that is long and useful to nobody.

On the data side, the README says all structured financial data (quotes, financial statements, valuation, consensus estimates, research notes, fund flows) comes from the Tencent 自选股 official interface, the same source behind the Tencent 微证券 mini program and the 自选股 app, with A-share and Hong Kong coverage described as a particular strength. Industry and macro material is cross-checked against primary sources, and every report labels each source with a grade of A, B or C.

Installing luopan and running a first research request

The README does not give a package manager command. What it does give is a single instruction: install the whole repository and invoke 罗盘, rather than hunting for two separate skills. Since the primary language is HTML and the deliverable is a skill definition, the practical path is to clone the repository into the skills location your agent reads. The README does not document that path or a version number, so check your own agent's skill directory before assuming one.

git clone https://github.com/zhangxiaoqiang1991/luopan.git

The README's own start examples are written as natural-language prompts, not flags. A first useful run is an industry question, because it exercises the router without the extra fork:

研究行业：帮我研究一下 AI Agent 行业

What you should get back, based on the README's description of the industry mode, is a map of the industry structure, the value chain, who holds pricing power, where profit sits, and whether entry makes sense. The published test-output reports for 知识付费, AI行业 and 跨境电商 follow that shape.

The second run worth trying is the ambiguous one, because it shows the routing behaviour:

帮我调研一下腾讯

The README states that luopan will ask you to choose investment, job hunting, or both before it searches. If you already know, say so up front and skip the prompt:

研究求职：我准备面试字节跳动，帮我判断是否值得去

What the three published reports actually contain

The review-output/ directory holds three worked examples dated 2026-07-12, each in HTML, Markdown and JSON. The README describes the split: HTML for reading, Markdown for keeping locally, JSON as a checkable data record. That three-format pattern is more useful than it sounds, because the JSON is where you can verify whether a number in the prose traces back to a labelled source.

The NVIDIA case is the investment line. The README quotes a conclusion that company quality passes but the price around 210.96 US dollars on the base date requires roughly 31 to 32 percent annual growth in normalised cash flow over five years, and fails the margin-of-safety test. The ByteDance case is the job-hunting line, and the README notes that because the company is not listed, the report refuses to assemble media estimates into a precise-looking revenue and valuation model. The Tencent case runs both lines from one fact base and reports that the investment and job-hunting conclusions can differ, with roughly 590.5 Hong Kong dollars described as closer to fair value than to a discount.

Those are the project's own published outputs, not independent verification. Read them as examples of the method's shape, not as current market calls.

Where luopan breaks down

The honest limitation is coverage asymmetry. The README describes A-share and Hong Kong coverage as a particular strength, and the whole structured data layer runs through a Tencent interface. Nothing in the README claims equivalent depth for US or European listings, yet the flagship investment example is NVIDIA. That is a gap worth noticing: the method may travel, but the data floor underneath it is described as strongest where Tencent is strongest.

The second limitation is that the router is a prompt-level design, not an enforced pipeline. The README says the root SKILL.md only routes, and that the full method lives in the two mode files. Whether the fork actually fires depends on the agent honouring the instruction to pause. A user who phrases a question ambiguously may get a report before the question is asked, and the README does not document a fallback for that.

Third, non-listed companies are handled by an explicit evidence boundary rather than a model. The README says such reports will state that public information is limited instead of fabricating precision. That is the right call, but it means the tool gives you less for a private employer than the job-hunting audience often wants.

Finally, the name is a problem for discovery. Searching for luopan returns feng shui compass results, which is why the repository is easier to find by its GitHub path than by its name.

The alternative: a general research agent with no router

The realistic alternative is not a competing product. It is the default behaviour of the same agent without luopan installed: you ask Claude Code or Codex to research a company and it produces a broad, well-formatted summary that mixes valuation, history, culture and hiring chatter into one document.

The difference is in what gets loaded. A general agent has no fixed source-grading rule, so a media estimate and a regulatory filing can appear side by side with equal weight. luopan's README states that every report labels sources A, B or C, and that companies are split into listed and non-listed with different evidence rules. It also forces the purpose question before any searching happens. A general agent will happily write 4,000 words on Tencent that answer neither an investor's question nor a candidate's.

The cost of that structure is flexibility. A general agent can pivot mid-research, follow a tangent, or answer a hybrid question without a fork. luopan deliberately narrows the question first, and the README treats that narrowing as the point rather than a nuisance.

Maintenance, licence and upgrade cost

The repository is not archived, and the last push was on 2026-07-18. There are no releases in the retrieved data, so there is no versioned upgrade path to follow: you track the main branch. That matters for cost. Because the method lives in Markdown skill files rather than compiled code, an update is a file change you can read before accepting, and the three review-output reports are dated, which gives you a way to see whether the output format shifted between revisions.

The licence is MIT. That permits reuse and modification with the licence and copyright notice retained, and it carries no warranty. This is not legal advice; read LICENSE in the repository if you plan to redistribute the skill files or the sample reports.

The real upgrade cost is not the code. It is re-reading modes/company/SKILL.md and modes/industry/SKILL.md when they change, because those files define the judgement model and a silent edit there changes what every future report concludes. The README does not document a changelog, so diffing those two files against your local copy is the only reliable way to know what moved.

Editorial conclusion

Adopt luopan if you already run Claude Code or Codex and your questions are about industry power, company quality, or whether an offer is worth taking, and you are willing to read a report that separates facts from judgement. Do not adopt it if you need real-time quotes, portfolio tracking, or a tool that works outside an agent runtime; the README describes a skill, not an app. Before relying on it, open modes/company/SKILL.md and check that the three-way prompt (investment, job hunting, or both) matches how you actually decide, and read one of the three published reports end to end to see how the A/B/C source grades are applied in practice.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. Project website
4. README
5. zhangxiaoqiang1991/luopan on GitHub