AmaGris User Guide

AmaGris analyses one stock with several AI agents, each taking a different role. Fundamentals, technical, news and sentiment analysts each pull their own market data; bull and bear researchers build their cases; a trader makes the call and a risk manager reviews it. The result is a markdown report with its reasoning attached.

⚠️ Disclaimer — Analyses and opinions produced by AmaGris are decision-support reference material, not investment advice or a recommendation to trade. LLMs can state things that are simply wrong, and failed data lookups are reported as errors in the report. Every investment decision, and its outcome, is yours alone.

1. The screen

When the app opens you see the menu bar at the top, docked panels on the left, and the work area in the middle.

Panels can be dragged to another dock position or torn off, and the layout is restored next time you start the app.

Menu bar

2. Getting started — register a model

An LLM does the analysing, so you must register a model first.

Add an LLM (Option ▸ AI Model…)

Click Add and fill in the fields.

Entries you add here are stored in ai-client-config.json, which the server merges with its built-in list (ai-config.json). It lives outside the install folder, so it survives reinstalls and updates.

Account sign-in (Claude · ChatGPT)

You can connect with an account instead of an API key. Tokens are stored encrypted (ai-oauth-tokens.json) and reused automatically after that.

3. Teams and roles

An AmaGris analysis runs exactly as the team defines it. Two windows split the job.

Team  →  Stage (execution order)  →  Member (= role + model)
                                       └ Role = persona + tools + reasoning

• Agent Team — the order of stages, and who (which role, on which model) is in each one.
• Agent Roles — what a role actually is: its system prompt, the tools it may call, whether it reasons.

The default team (4 stages)

Parallel vs sequential — Members of a parallel stage receive only the output of earlier stages and never see each other's work. Members of a sequential stage receive all earlier stages plus the members ahead of them in the same stage.

The debate stage is parallel on purpose: bull and bear must build their cases independently. If they can see each other, one drifts toward the other.

Editing a team (Option ▸ Agent Team…)

• Keep several teams and mark one as the default.
• Add, remove and reorder stages, and switch each one between parallel and sequential.
• Assign a role and a model to every member. Every member needs a model before the team can be saved — a member without one stops the run at that point with a prompt to pick a model.
• Reset restores the default template.

💡 Roles can run on different models. A practical split is a fast, cheap model for the analysts (who mostly gather and summarise) and a strong reasoning model for the trader and risk manager (who judge).

Editing a role (Option ▸ Agent Roles…)

Role definitions live in agent-roles-config.json. When that file is valid it is the only source of truth — a role you delete does not come back from the built-in defaults. If you wipe them by accident, press Reset.

4. Analysing a stock (/analyze)

Three ways to run it

1. Slash command — type /analyze 삼성전자 or /trade 005930 in the chat box
2. Plain language — a message that ends in the "〈stock〉 분석" form starts an analysis automatically. (If anything follows it — e.g. 삼성전자 분석 자료 찾아줘 — it is treated as ordinary chat)
3. Double-click in the watchlist — see §5

Both company names and six-digit ticker codes work.

Progress

An analysis takes several minutes. Each stage appears as it finishes.

🔍 Four analysts working through the data…
💬 Bull and bear cases…
📊 Trader's final call…
🛡️ Risk manager reviewing…

Report structure

# Trading analysis report — Samsung Electronics
Market: KR · Team: Default analysis team

## 1. Analysis
### Fundamentals analyst
…
### Technical analyst
…
## 2. Debate
### Bull researcher / Bear researcher
## 3. Decision
### Trader
## 4. Risk
### Risk manager
## Final verdict
(trader's call plus the risk manager's adjusted confidence)

The confidence in Final verdict comes from the risk manager where one exists — as the last gate, it overrides the trader's figure.

Failed lookups are reported as errors rather than invented. Check each analyst section for errors before you read the conclusion.

5. The watchlist

Managed from the Watch List panel on the left.

Groups

Pick a group from the select box at the top; ＋ adds a group and － deletes one. The grid shows only the selected group.

Adding stocks

Add stock… opens a search dialog. Type a query and press Enter, pick a result, choose the group, then Add. Double-clicking a result adds it immediately, and the dialog stays open so you can keep adding.

Stock search works without any key — it uses the DART company index when a DART key is present, and Naver's autocomplete otherwise. Note that a few companies are listed under an official name that differs from the common one (엔씨소프트, for example, is registered as NC), so you may need the official name.

Running an analysis

Double-click a row in the watchlist grid and /analyze runs for that stock in the active AI chat session.

The watchlist is saved to watchlist-config.json immediately, outside the install folder, so it survives reinstalls and updates.

6. Batch analysis (Import Stock)

To analyse many stocks at once, load a list file (.ini) via File ▸ Import Stock….

File format

One stock per line. INI conventions are accepted.

; comments start with ; or #
[watchlist]         ; section headers are ignored
삼성전자
005930
third=SK하이닉스     ; for key=value lines the value is used

• Blank lines are ignored
• Lines starting with # or ; are comments
• [section] headers are ignored
• For key=value lines, the part after = is the stock name

On load, a chat session is opened if none is active, the app waits up to 12 seconds for the model connection to be ready, and then works through the list in order. If it is not ready you get "the AI session is not ready" — check the model connection and try again.

Each stock takes several minutes. A long list takes proportionally longer and costs proportionally more in LLM calls.

7. Market data and API keys

Agents pull data through these seven tools. Which tools a role may use is set in Agent Roles.

The "key required" column assumes KIS as the quote source. Choose Naver Finance and prices, fundamentals and indicators work without a key too — only filings (DART) still need one.

Sentiment is scored by the model of whichever role called the tool — there is no separate model for it.

Choosing a quote source and entering keys (Option ▸ Settings… ▸ 시세서버)

The 시세서버 (Quote server) tab in Settings is where you pick where quotes come from and enter the keys it needs. Selecting a source immediately shows its characteristics in the description box below.

If you have no keys at all, pick Naver Finance — analysis works straight after install. For something stable to rely on long-term, prefer KIS (an official API whose format will not shift).

With data.go.kr the quote is the previous session's close. Reports carry the reference date (asOf) alongside it, so it cannot be mistaken for a live price — but it is the wrong basis for an intraday call.

Either service key works — data.go.kr issues an encoded and a decoded form, and the app normalises whichever you paste.

ℹ️ Figures can differ between sources. PER, for instance, is computed from trailing results by KIS and from confirmed annual results by Naver, so the same stock shows different values. Neither is wrong — the basis differs — and every report states which source a figure came from.

The DART key is used for filings and stock search regardless of the quote source, so it always sits at the bottom of the same tab.

How keys are stored

Keys you enter are encrypted (AES-256-GCM sealed) in ai-settings.json — the same scheme as account sign-in tokens. Opening the file shows no plaintext key. It lives outside the install folder (userData), so it survives reinstalls and updates.

Using environment variables instead (optional)

For automation you can set keys in the environment instead of the settings screen. Environment variables take priority over the settings screen.

Where to get keys — DART: opendart.fss.or.kr (free, issued straight after email sign-up), KIS: Korea Investment KIS Developers (requires a brokerage account in your own name; can be opened remotely), data.go.kr: data.go.kr (free).

Without a key the matching tool fails and the report says so.

You can use AmaGris with no keys at all — set the quote source to Naver Finance and prices, fundamentals, indicators, news, sentiment and stock search all work. Only filings (DART) are missing.

8. Ordinary chat and slash commands

Beyond analysis, AmaGris works as a general AI chat. Open a new session and just ask. Point a session at a working folder and it can read, search and edit files there.

Slash commands

/find, /grep and /help never call the LLM, so they answer immediately and cost no tokens.

Command approval

When the AI wants to run a shell command an approval prompt appears. Read what it intends to run before allowing it. Dangerous commands are blocked outright, and execution is time-limited.

9. Settings (Option ▸ Settings…)

10. Where things are stored

Settings and data live outside the install folder (%APPDATA%\AmaGris) and survive reinstalls and updates.

To back up, copy that folder. ai-oauth-tokens.json is encrypted and its key lives with the installed app, so the file alone cannot be decrypted if it leaks.

11. Automatic updates

The app checks for a newer version on start-up.

• A new installer is available — "Version x.y.z is available. Install it?" Accept and it downloads, installs and restarts.
• Only the app content changed — "There is an update available." Accept and it downloads now, applying it on the next launch.

Choose Later and the app just runs, asking again next time. If the network is down or the server does not answer, it passes silently and the app opens normally.

The current version is under Help ▸ About.

12. Worth knowing

Analyses are slow. Eight roles each call an LLM, and several of them call tools as well. Several minutes per stock is normal. To speed it up, cut stages or members from the team.

Do not read only the conclusion. If an analyst section hit a data error, everything built on top of it — the debate, the decision, the risk review — is weaker than it looks.

LLMs get things wrong. The figures fetched by tools are real data, but the sentences interpreting them were written by a model. Be especially sceptical of claims with no numbers cited.

Try different models. For the same stock, the conclusion shifts depending on which model you put behind the trader and the risk manager. A strong reasoning model in the judgement roles gives steadier results.

Summary: your first run

1. Install and launch the app.
2. Register a model under Option ▸ AI Model… (or sign in with an account).
3. Assign a model to every member under Option ▸ Agent Team…. (all of them)
4. Under Option ▸ Settings… ▸ 시세서버, choose the quote source. With no keys, pick Naver Finance and it just works. (Enter KIS and DART keys here if you have them.)
5. Open a session with File ▸ New Session and type /analyze 삼성전자.
6. Keep the stocks you follow in the Watch List and double-click to analyse.