Idea: an optional desktop app (ui/) that drives the existing commands without duplicating them

[fatihserhatturan]

What it is
I've been running my search through this framework and built a small macOS desktop app on top of it for my own use. Before polishing it into a PR, I'd like to know whether something like this fits upstream at all, or whether it belongs in a fork. I've read CONTRIBUTING, including the part about orchestration layers and wrappers (#44, #49, #66) and your reply in #332, so I'd rather ask first than send you a 4k-line PR.

The app gives a visual view of the pipeline:

Lists: scraped jobs grouped by fit, applications grouped by tracker status, and a side panel showing /rank's strengths and gaps.
Documents: PDF preview of the compiled CV and cover letter.
Runs: the commands appear as a live activity feed.
(Screenshots use made-up demo data.)

How it stays out of the specs' way
The design goal was to add zero workflow logic:

Commands run unchanged. Every action is the existing slash command, e.g. /scrape, /rank, /apply , /outcome, /interview, /upskill, /html-report, /setup --section. They run through the Claude Agent SDK in the repo root with settingSources: ["project"] and Claude Code's own preset system prompt. So CLAUDE.md, the skills, the commands and .claude/settings.json load exactly as in the CLI, and a methodology change upstream reaches the app with no app change.
The app writes no state files. It only reads seen_jobs.json, job_search_tracker.csv, documents/applications/* and the compiled PDFs. Every write still happens inside the commands, so /outcome stays the single writer of the tracker, which was the concern you raised in #332.
Stop points stay with the user. The commands' stop points (e.g. /apply's "proceed to drafting?") end the turn. The app shows a reply box and resumes the same session; AskUserQuestion is rendered as a form.
Tool permissions are layered on top. Read-only tools and the same commands settings.json already allows (portal CLIs, tools/*.py, LaTeX compiles, rm -f of build artifacts in cv/ and cover_letters/) run without asking. Anything else shows an approval prompt. Writing outside the repo, git push, sudo and rm -r are refused. settings.json itself isn't touched, so security_guards stays green.
Footprint outside ui/: a few .gitignore lines (build output and run transcripts) and a short README pointer. No new commands, no changes to skills or tools.
Locked down by default: no network port (renderer ↔ main over IPC only), contextIsolation and sandbox on, a strict CSP, PDFs served only from allowlisted folders. The Claude token is stored encrypted via the macOS keychain (safeStorage).
Tests: 50 bun test cases in ui/tests/. They cover tracker CSV parsing (including legacy 13-column rows and space-spelled statuses), the seen_jobs.json wrapper/bare forms and legacy verdicts, outcome.md parsing, the permission classifier, path-traversal rejection, theme contrast, and i18n key parity.
It also ships Turkish and English UI strings. Claude's chat replies follow the app language, while document language still follows the repo's rules. Adding a language means adding one dictionary file, which felt in the spirit of fork-and-adapt.

The honest costs
It is a resident process. That's exactly what you described as a real cost in a run-and-done template. It also pulls in Electron and the Agent SDK, so it's heavy for something optional.
Packaging is macOS-only. It's Apple Silicon, ad-hoc signed, with bun run install-app. The code itself isn't macOS-specific, but I haven't built or tested it elsewhere.
CI and maintenance. It's another surface to keep working, and I don't have a way for CI to exercise the live agent path.
The question
Which of these would you prefer?

Upstream as an optional ui/ folder. I'd split it the way you like (#73): the core app first, then design, then i18n, each as its own PR, with CI only typechecking and unit-testing it.
Keep it out of upstream. I'd publish it as a standalone repo that points at a user's checkout of this template, and list it under Community forks & adaptations (#78).
Either answer is fine with me. I'd rather it lives wherever it costs you the least.

[senademirbas]

Selam. Türkiye için hangi ilan kaynaklarını kullanıyordunuz veya kullanıyor musunuz? Kariyer.net veya Youthall için bir portal skill’i yazmış mıydınız, yazdıysanız paylaşma veya türkiye ekosisteminde ban yemeden kullanımınızdan bahsetme şansınız var mı? Henüz denemedim repoyu ve Türk birini görünce sormak istedim. :)

[fatihserhatturan]

Selamlar, kariyer.net için bir tool geliştirmek üzerinde çalışıyorum çalışır hale geldiğinde hem github profilimde hem de bu konuşma üzerinden sizinle paylaşırım. Eğer benden önce siz geliştirebilirseniz siz de bana iletirseniz memnun olurum :)

[senademirbas]

Teşekkür ederim yanıtınız için, ben de katkı sağlamak istiyorum ancak başka birkaç işle daha uğraşıyorum. Repoyu biraz kurcalayacağım malum trde biraz sıkıntılı çok ümitli değilim. Ama eğer başarırsam sizlere de iletirim :)

[MadsLorentzen]

@ealevli posted a kariyer.net portal skill for the Turkish market in the community forks thread: #78 (fork: https://github.com/ealevli/ai-job-search, skill at .agents/skills/kariyer-net-search/). Nothing for Youthall yet. /add-portal scaffolds a new portal skill if you want to build one.

[senademirbas]

Thanks a lot for pointing that out! I'll check out ealevli's fork and the Kariyer.net skill. if I get some bandwidth to work on Youthall, I'll update the community thread. Thanks again!

[MadsLorentzen]

Thanks for asking before writing the PR, and for reading #332 first. The design is careful. The commands run unchanged, the app writes no state, /outcome stays the only writer and settings.json is untouched. That shape keeps a UI from drifting away from the specs.

My answer is your second option: a standalone repo, listed in #78. The reasons are the costs you named yourself:

• A resident Electron process plus the Agent SDK is a heavy dependency for something optional.
• Packaging is macOS-only.
• CI here can't exercise the live agent path, so upstream would carry a surface it can't test.

Meanwhile every methodology change lands in the specs the app already reads. As a standalone repo that points at a user's checkout, it still picks up upstream changes with no app change, which is the property you designed for, and you can release it on your own schedule.

When it's published, reply in #78 with the link. The checks at the top of that thread apply, and for an app the safety pass carries the most weight: what it fetches, where the token lives, and what the permission layer runs without asking. Please also say in the README how the app authenticates. The Agent SDK docs say that, unless Anthropic has approved it, third-party apps may not offer claude.ai login and should use API-key authentication: https://code.claude.com/docs/en/agent-sdk/overview

[fatihserhatturan]

Thanks for the careful review, and for pointing at the Agent SDK terms. That settled the auth question.

I went with the standalone repo: https://github.com/fatihserhatturan/ai-job-search-desktop

It's still a work in progress. I've created it but I'm still working on it, and I'll add it to #78 once it works fully and correctly end to end, after going through the checklist at the top of that thread.

What changed from the design I described here:

• Auth is an Anthropic API key only. There's no claude.ai or subscription login. A CLAUDE_CODE_OAUTH_TOKEN in the environment is dropped at startup and never reaches agent runs. A run won't start without a key, so the agent can't fall back to a Claude Code login stored on the machine. The README says this up front.
• The key is encrypted with the macOS keychain (Electron safeStorage), stored with mode 0600, and only decrypted into the main process's environment. The window never sees it.
• Fetching: the app's own code makes no network requests and opens no ports. The renderer runs under connect-src 'self' with bundled fonts and icons. All traffic comes from the agent runs: the Anthropic API, plus the workflows' own WebSearch/WebFetch and portal CLIs.
• Permissions: the checkout's .claude/settings.json is applied first. After that, a classifier allows read-only tools, writes inside the checkout, and a short list of shell commands matched against the whole command (portal CLIs, tools/*.py, LaTeX, build-file cleanup). Anything else asks. Writes outside the checkout, git push, sudo and rm -r are always denied. The full table is in the README.
• The repo was built from a fresh history and ships none of the framework's files. It reads the user's checkout at runtime and was tested against upstream 0f6480d.

Thanks again!