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 same app also recommends KOSPI stocks, keeps your watch list, places orders on a Korea Investment & Securities (KIS) account, and works as a general AI chat with file tools and a terminal.

⚠️ 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 flagged as a warning just before the conclusion. Orders are sent only after you approve each one yourself, and 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 right, and the work area in the middle.

Panels can be dragged to dock elsewhere or pulled out, and their layout and sizes are restored the next time you start the app — including panels stacked as tabs in the same spot.

Menu bar

2. Getting started — registering a model

Analyses and chats are carried out by an LLM, so register a model first.

Adding an LLM (Option ▸ AI Model…)

Press 추가 (Add) and fill in the fields.

Entries you add are saved in ai-client-config.json and shown together with the built-in list. They are stored outside the install folder, so they survive reinstalls and updates.

Signing in with an account (Claude · ChatGPT)

When the API Type is Claude or OpenAI, you can connect with an account instead of an API key (Gemini uses API keys only). Enter a Name first, then press the sign-in button.

• Claude 계정으로 로그인 (sign in with Claude) — sign in in the browser, paste the code it shows into 인증 코드 (auth code) and press 코드 적용 (apply code).
• ChatGPT 계정으로 로그인 (sign in with ChatGPT) — sign in in the browser and the code is passed back automatically.

Sign-in tokens are stored encrypted (ai-oauth-tokens.json) and used automatically from then on.

3. Agent teams and roles

A stock analysis runs according to the team layout. It is set up in two windows.

Team  →  Stage (run from top to bottom)  →  Member (= Role + Model)
                                             └ Role = persona + tools + reasoning on/off

• Agent Team — the order of stages, and who (which role) joins each stage with which model.
• Agent Roles — what each role actually is (system prompt, tools it may use, whether it reasons).

When you save, the app builds an analysis agent for each member and an analysis procedure (skill) for each team, and refreshes the team list in every open chat tab.

Default team — 기본 분석팀 (4 stages)

Parallel (independent) vs sequential (cumulative) — members of a parallel stage receive only the reports of earlier stages and do not see each other's results. Members of a sequential stage receive all earlier stages plus the members before them in the same stage.

The debate stage is parallel so that bull and bear build their cases independently, without seeing each other's arguments. If they could, one would get pulled toward the other.

Editing teams (Option ▸ Agent Team…)

• Keep several teams and press 기본 팀으로 설정 (set as default team) on one. New sessions always start with the default team (●); switch teams in the team dropdown on the working-folder row at the bottom of each chat tab.
• Edit stages with 단계 추가 (add stage), 단계 삭제 (delete stage) and ▲▼, and set each stage's mode to 병렬 (각자 독립) (parallel) or 순차 (누적) (sequential).
• Give each member a role and a model. Every member must have a model before you can save. A role that uses tools also cannot be saved with a model that does not support tool calls.
• 팀 초기화 (reset team) restores the default template.

💡 Each role can use a different model. A practical setup is a fast, cheap model for analysts that mostly collect and summarise, and a strong reasoning model for the trader and risk manager who make the calls.

Editing roles (Option ▸ Agent Roles…)

The roles you define here appear in the role list of the Agent Team window. Role definitions are saved in agent-roles-config.json, and while that file is valid it is the only source — a built-in role you delete does not come back. If you delete everything by mistake, press 역할 초기화 (reset roles).

4. Stock analysis

How to run it

1. Slash command — type /analyze 삼성전자 or /analyze 005930 in the chat (a stock name or a 6-digit code both work)
2. With a specific team — /analyze_<team key> <stock> (to use a team other than the one chosen in the tab; each team's name is listed among the skills in /help)
3. Double-click in the watch list — see Chapter 6
4. Batch analysis — see Chapter 7

A working folder is required, because the analysis agents leave their reports inside it. Pick one first with 📁 폴더 선택 (select folder) at the top of the chat tab.

Plain requests such as "analyse Samsung Electronics" are handled as ordinary chat. Start an analysis with /analyze.

If the stock cannot be found you get a notice — try again with the listed name or the 6-digit code, or search for it with 종목 추가… (add stock) in the watch list panel.

While it runs

An analysis takes several minutes. It first fetches the current price to confirm the stock (if that fails, it stops with a notice instead of starting), then goes through the stages in order, with a delegation card for each role showing its progress. A card turns into ✔ 위임 완료 (delegation done) when finished, and expanding it shows that role's full report.

A single progress line (elapsed time · what is happening now) stays at the top. When the analysis ends the process folds away and the final answer stays below a summary line (time taken · steps · tool calls). Click the summary line to unfold the process again.

What the result looks like

## 역할별 요약          (summary per role)
(2–3 lines per role)

## ⚠️ 데이터 경고        ← data warning, only when some data failed
## 최종 결론            (final conclusion)
- Trader: decision · confidence
- Risk manager: review · decision · confidence
- Final decision / final confidence

> ⚠️ disclaimer
> 📌 order ticket: name (code)

• The final decision and confidence follow the last judging role (the risk manager). If the risk manager disagreed with the trader, both are shown. Confidence runs from 0 to 100.
• Data that could not be fetched is never made up. A one-line notice appears the moment a lookup fails, and when the analysis ends the app inserts a ⚠️ 데이터 경고 block (which data failed, how many times) right before the final conclusion. Items that succeeded on a later retry within the same analysis are left out. If the cause is an API key, fix it in Settings ▸ 시세서버.
• If a price in the final conclusion is off from the current price by an order of magnitude, a ⚠️ 가격 확인 필요 (check price) warning is added.
• The 주문 티켓 열기 (open order ticket) button below the answer opens the KIS order window with that stock filled in. Nothing is sent until you approve it there. (Chapter 8)

Before reading the conclusion, check whether there is a data warning.

5. KOSPI recommendations

Choose File ▸ 코스피 종목 추천... and a window asks for the period.

After 추천 시작 (start), it works like this:

1. First screening across all KOSPI stocks — ETFs, preferred shares, SPACs and suspended, administrative or warning-designated stocks are excluded. For medium and long term, only stocks with recent financials (ROE, net income) are kept.
2. A dedicated sub-agent reviews up to 20 candidates one by one and rates each 추천 가능 (recommend), 관망 (wait), 제외 (exclude) or 자료 부족 (insufficient data).
3. Up to 5 stocks are recommended in a table — rank · name (code) · reasons · main risks and counter-arguments · what would change the call · data date.

• If few stocks qualify, it does not pad the list to 5. It gives no target prices, stop-losses, quantities or weights.
• It needs a chat with a connected model and a working folder, and cannot start during a batch analysis.
• Reviewing many stocks takes time. You can stop it with Stop in the chat.
• You can also type /recommend_kospi in the chat (it will ask for the period).

6. Watch list

Managed in the Watch List panel on the left.

Groups

Pick a group from the select box at the top; ＋ adds a group and － deletes the current one. The grid (No. · name · code · delete) shows only the stocks of the selected group. If you delete every group, a 기본 (default) group is recreated.

Adding stocks

Press 종목 추가… (add stock) to open the search window. Enter a name or a 6-digit code and press 검색 (search) → pick a result → choose the group → 추가 (add). Double-clicking a result row adds it right away, and the window stays open so you can keep adding.

Stock search works without any API key — with a DART key it uses DART's company-name index, otherwise Naver's autocomplete. A few stocks whose common name differs from the official one (e.g. NCSoft → official name NC) may only show up under the official name.

Analysing and ordering

• Double-click a row to run /analyze for that stock in the active chat session (a new session opens if there is none).
• Select a row and press 주문… (order) to open the KIS order window with that stock filled in.

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

7. Batch analysis (Import Stock)

To analyse many stocks in one go, load a list file (.ini) with File ▸ Import Stock....

File format

One stock per line. INI conventions are accepted.

; comments start with ; or #
[Watchlist]          ; section headers are ignored
삼성전자
005930
stock3=SK하이닉스     ; in key=value form the part after = is used as the name

• Empty lines are ignored
• Lines starting with # or ; are comments
• [section] headers are ignored
• In key=value form the value after = is used as the stock name

Progress and results

• If there is no active chat session, a new one opens and the app waits up to 12 seconds for the model connection. If it is not ready you get "AI 세션이 준비되지 않았습니다" (AI session not ready); check the model connection and try again. A working folder is also required.
• Each stock starts from a cleared conversation and runs one /analyze. Progress notes such as ▶ [i/N] … 분석 중… and ✓/✗ stock → file stay in the chat.
• Input is blocked while it runs. Press Stop to end it.
• Results are saved next to the .ini file in a <file name>_분석_<date_time> folder — one NN_<stock>.md per stock and a summary table _분석요약.md (stock · result · final decision · confidence · file) — and the folder opens when it is done.

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

8. KIS stock orders

With a Korea Investment & Securities (KIS) account you can buy and sell KOSPI and KOSDAQ stocks for cash (limit and market orders). Margin, scheduled and automated trading are not available. Every order is sent only after a preview and your own approval; the AI cannot place orders.

Setup — Settings ▸ KIS 주문

1. Turn on KIS 주문 사용 (매 주문마다 승인 필요) (use KIS orders, approval required each time).
2. Choose the order environment — 모의투자 (먼저 검증) (paper trading, verify first) or 실전투자 (live).
3. Enter that environment's App Key · App Secret · account number (first 8 digits) · product code (last 2 digits, e.g. 01).

Paper and live details are stored separately and encrypted. Order keys are not filled in from the quote server tab or environment variables — enter them here. Try paper trading first.

Opening the order window

• File ▸ KIS 주식 주문
• Pick a stock in the watch list and press 주문…
• 주문 티켓 열기 below an analysis result
• Selecting a row in the window's holdings tab fills in a sell ticket for that stock.

The order window is a single separate window; if it is already open it comes to the front.

Placing an order

1. Type the stock (with autocomplete) and press 종목 확인 (confirm stock).
2. Choose 매수 (buy) / 매도 (sell) and 지정가 (limit) / 시장가 (market).
3. Set the quantity with the ± buttons or the 10% · 25% · 50% · max buttons.
4. The limit price is not typed in; move it with the tick-size −/+ buttons and 현재가 갱신 (refresh price).
5. Press 주문 미리보기 (KIS 주문 가능 조회) (preview) and the approve button changes to something like 모의 매수 승인·전송 (approve & send paper buy). A preview is valid for 2 minutes (the button shows the time left).
6. For a live order you must tick 실계좌 주문임을 확인했습니다 (I confirm this is a live account order) before approving. The Enter key never approves an order.

An order number does not mean the order was filled. Check fills in the 오늘 주문 (today's orders) tab. If the response is uncertain, the order is not resent automatically.

Account, amend and cancel

• The top bar shows 모의투자 / 실전투자 and the account; KIS 조회 loads deposits, total valuation and net assets.
• Tabs: 미체결 (open orders) · 오늘 주문 (today's orders) · 보유 잔고 (holdings) · 앱 기록 (app log).
• 정정 (amend: quantity or limit price) and 취소 (cancel: all remaining) on an open order also go through preview → approval.

When an order needs checking

If an order's result is uncertain, a ⚠ 접수 확인 필요 (check receipt) banner appears at the top and new orders, amendments and cancellations on that account are blocked (lookups still work). Check in the 오늘 주문 tab whether it was actually received, then press 확인함 · 제한 해제 (checked · lift block).

A record of each order is written to the kis-orders folder just before it is sent.

9. Market data and API keys

The agents fetch data themselves with the tools below. Which role may use which tool is set in Agent Roles.

The sentiment score is graded by the model of the role that called the tool — no separate model is set for it.

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

In the 시세서버 (quote server) tab of Settings, choose where quotes come from and enter the keys it needs. Only the fields the chosen source needs are shown, and a description box explains it.

If you have no keys at all, choose Naver Finance — analysis works straight after install. For long-term, stable use KIS is recommended (an official API whose format does not change).

With the Public Data Portal, quotes are the previous business day's close. Results show the reference date, so you will not mistake it for today's price, but it is not suited to intraday decisions. The portal key can be pasted as either the Encoding or the Decoding key.

ℹ️ Values can differ between sources. PER, for example, uses recent earnings at KIS and confirmed annual earnings at Naver, so the same stock can show different values. Neither is wrong; they are calculated on different bases.

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

You can use AmaGris with no keys at all — with Naver Finance as the quote source, prices, financials, indicators, news, sentiment and stock search all work; only filings (DART) are missing. Tools without a key fail and are listed in the data warning before the conclusion.

How keys are stored

Keys you enter are encrypted (sealed with AES-256-GCM) and saved in ai-settings.json, the same way as account sign-in tokens; opening the file shows no plain-text key. It lives outside the install folder, so it survives reinstalls and updates.

Using environment variables (optional)

For automated setups you can use environment variables instead of the settings screen. Environment variables take precedence over values set on screen.

KIS orders do not use environment variables (enter them only in Settings ▸ KIS 주문).

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

10. General chat and work tools

Besides analysis, AmaGris works as a general AI chat — open a new session and just ask. If you set a working folder, the AI can read, search and edit the files in it. A folder used for the first time asks for folder trust; in a trusted folder, file edits and new files are not confirmed one by one.

Sending messages while it works

If you type while the AI is working, the message goes into a queue and is delivered when the AI moves to its next step. Anything not delivered by the end is sent automatically right after.

• 지금 보내기 (send now) on a queued message stops the current work and sends it immediately; ✕ cancels it and puts it back in the input box.
• Slash commands and image attachments cannot be sent while the AI is working.

The chat view

Each request and its answer are grouped together. When the work ends the process folds away and the final answer stays below a summary line; click the summary line to unfold it again. When the AI hands work to another agent a delegation card appears, and for work handed off in the background the AI carries on by itself once the completion report arrives (up to 20 times in a row). A delegation stops after 15 minutes without progress or after 2 hours.

The AI can also open a web page in a window inside the app to check it. Before opening an address other than a development server on your own PC, it asks for approval.

Terminal and the ▶ Run button

• Choose View ▸ Terminal to open a terminal in the right panel. It starts in the working folder of the chat tab you are on (PowerShell on Windows), and the + on its tab bar opens more.
• Commands the AI suggests for you to run yourself (bash, PowerShell or cmd blocks) get a ▶ Run button. Clicking it opens the terminal in that chat's working folder with the matching shell and runs the command. If a terminal tab for the same folder and shell is already open, it is reused. Check the result in the terminal.
• The terminal and the Run button are available in the desktop app only (shared views show only Copy).

Find in chat (Ctrl+F)

Press Ctrl+F in a chat to open a search box at the top right — handy for finding a stock or figure again in a long analysis or conversation.

• Matches are highlighted as you type (case-insensitive), and your position is shown as 1/3.
• Enter or the ↓ button goes to the next match, Shift+Enter or the ↑ button to the previous one (wrapping around).
• Esc or ✕ closes it and clears all highlights. If you have text selected in the chat when you press Ctrl+F, it becomes the search term.
• Each chat tab has its own search box.

Slash commands

Instant commands such as /find, /grep and /help do not call the LLM, so they use no tokens.

Approving commands

When the AI wants to run a shell command, an approval window (AI requests to run a command) appears. Check the command and folder, then choose Allow or Deny (Enter = Allow, Esc = Deny). Ticking 이번 세션에서 자동승인 (auto-approve this session) stops it asking again in that session — except for commands that must always be confirmed, such as git push. Dangerous commands are blocked separately, and every command runs with a time limit.

11. Session sharing

You can watch an ongoing conversation live in a browser on your phone or another PC.

• Click the 공유 (Share) badge at the top of the chat view to open the sharing settings (PIN · permissions · server). When it is on, a share address and QR code appear and the badge changes to 공유 중 · N명 (sharing · N people). For permissions, choose view only or can send chat commands.
• Sharing needs a relay server. AmaGris does not provide a public relay, so run your own and register it under Option ▸ Session Sharing Servers... first. The share dialog preselects the server you last confirmed.
• In the server window, 로컬 서버 (local server) fills in the address of a sharing server running on this PC (ws://localhost:4840) and ticks ws:// 허용 (allow ws://). 연결 테스트 (connection test) checks the connection.

Running your own sharing server

Download the package from the 세션 공유 서버 (session sharing server) card on the website's Download page. The sharing server does not store chat content (it keeps only host identities and share mappings).

Windows (zip)

1. Extract the whole zip and put the amagris-share folder anywhere (do not run it from inside the zip).
2. Run amagris-share.exe. If SmartScreen warns, click More info → Run anyway; if Windows Firewall asks, click Allow.
3. Register the address to enter in AmaGris settings shown in the console under Option ▸ Session Sharing Servers... (for a ws:// address, tick ws:// 허용). On the same PC the 로컬 서버 button is enough; other PCs and phones on the same network connect with ws://<this PC's IP>:4840.
4. Closing the console window (or Ctrl+C) stops the server.

On the same PC or network no settings file is needed. To change the port, address or certificates, copy config.sample.json to config.json and edit it.

Linux server (tar.gz · Node 18 or later)

1. Extract it and run npm install --omit=dev in the folder.
2. Create config.json in the same folder (required — public address siteUrl, https on/off, certificate paths).
3. Start it with ./start.sh (stop with ./stop.sh) and open 4840/tcp in the firewall.
4. Register wss://<domain>:4840 in AmaGris (or ws://<server IP>:4840 with ws:// 허용 for plain HTTP on a LAN).

All settings are described in the README.txt inside the package.

12. Settings (Option ▸ Settings…)

MCP servers and session sharing servers are registered in their own windows under the Option menu, not in Settings tabs.

13. Where things are stored

Settings and data are stored outside the install folder (%APPDATA%\AmaGris), so they survive reinstalls and updates.

Chat history from version 1.2.0 or earlier is carried over automatically once, on first start (the original is not deleted).

To back up, just copy this folder. ai-oauth-tokens.json and the encrypted keys cannot be restored to plain text from those files alone.

14. Automatic updates

The app checks for a new version 12 seconds after it opens and then every 4 hours. When there is one, a notice card appears in the lower-right corner.

• Nothing is downloaded until you press 업데이트. Progress is shown on the card.
• 나중에 (Later) keeps you working and the notice returns at the next check.
• If the download fails, the "업데이트를 받지 못했습니다" (update failed) card offers 다시 시도 (retry). If there is no network or the server does not respond, the check is skipped quietly and the app works normally.

Check your current version under Help ▸ About. It shows something like Version : 1.5.0 and Release : AS-builddate-patch; the Release line pinpoints the exact build, so please include it when you contact us. The patch number starts again from 1 whenever the installer version changes.

15. Good to know

Analyses take a while. Eight roles each call an LLM, and some of them call tools as well. Parallel stages also run two members at a time, so several minutes per stock is normal. To speed things up, remove stages or members from the team.

Do not read only the conclusion. If there is a data warning, every debate, decision and risk judgement built on top of it is weaker. Expand the delegation cards to read each role's full report.

LLMs make mistakes. The figures fetched by tools are real data, but the sentences interpreting them are written by the model. Be especially sceptical of claims that cite no numbers.

Try different models. Even for the same stock, the conclusion changes with the models assigned to the trader and risk manager. Strong reasoning models tend to be more stable for the judging roles.

Try orders on paper trading first. Before switching to a live account, run through ordering, amending and cancelling once in the paper-trading environment.

Summary: first-time flow

1. Install and start 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... (every member needs one before you can save)
4. Choose a quote source under Option ▸ Settings... ▸ 시세서버. With no keys, pick 네이버증권 (Naver Finance) and it works right away. (Enter KIS or DART keys here if you have them.)
5. Open a session with File ▸ New Session, choose a working folder with 📁 폴더 선택, and type /analyze 삼성전자.
6. Keep stocks you follow in the Watch List and double-click to analyse them.
7. To place orders, set up Settings ▸ KIS 주문 with paper trading first.