token-tv 0.2.0__tar.gz

token_tv-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 click6067-ship-it
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

token_tv-0.2.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.4
+Name: token-tv
+Version: 0.2.0
+Summary: Your AI usage limits on a $5 desk clock: Claude, Codex and Grok on a 240x240 Wi-Fi clock
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/click6067-ship-it/token-tv
+Project-URL: Demo, https://token-tv.vercel.app
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: Pillow<13,>=10.2
+Dynamic: license-file
+
+<h1 align="center">TokenTV</h1>
+<p align="center">
+  <a href="https://github.com/click6067-ship-it/token-tv/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/click6067-ship-it/token-tv"></a>
+  <a href="https://github.com/click6067-ship-it/token-tv/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://hackaday.com/2026/10/06/smalltv-hacking-with-surprisingly-little-fuss/"><img alt="Featured on Hackaday" src="https://img.shields.io/badge/featured%20on-Hackaday-1a1a1a"></a>
+  <a href="https://github.com/steipete/CodexBar#desk-display"><img alt="Listed in CodexBar" src="https://img.shields.io/badge/listed%20in-CodexBar-555555"></a>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/click6067-ship-it/token-tv/main/docs/images/real-clock.jpg" alt="TokenTV on a real tiny desk clock"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/click6067-ship-it/token-tv/main/docs/images/clock-faces.png" alt="Six clock faces (sample data)"></p>
+
+Your Claude and Codex usage limits on a ~$5 Wi-Fi desk clock. No firmware flashing.  
+**Try it:** [live demo](https://token-tv.vercel.app), `npx token-tv demo` or `uvx token-tv demo`, no clock or login needed.  
+**Set it up:** give this repo to your AI and say *"Set up TokenTV for me."* It follows [AGENTS.md](https://github.com/click6067-ship-it/token-tv/blob/main/AGENTS.md).  
+**Make your own face:** no clock needed, start from the [Game Boy example](https://github.com/click6067-ship-it/token-tv/tree/main/examples/gameboy) and ask your AI to change it. [Guide](https://github.com/click6067-ship-it/token-tv/blob/main/docs/clock-faces.md) · [Share it](https://github.com/click6067-ship-it/token-tv/issues/new?template=share_a_face.md)  
+Details: [how it works](https://github.com/click6067-ship-it/token-tv/blob/main/docs/stock-photo-display.md) · [setup](https://github.com/click6067-ship-it/token-tv/blob/main/docs/setup.md) · [compatible clocks](https://github.com/click6067-ship-it/token-tv/blob/main/docs/hardware-compatibility.md) · [CodexBar input](https://github.com/click6067-ship-it/token-tv/blob/main/docs/codexbar.md) · [Apple Watch](https://github.com/click6067-ship-it/token-tv/blob/main/docs/apple-watch.md) · [한국어](https://github.com/click6067-ship-it/token-tv/blob/main/README.ko.md)  
+
+<p align="center"><a href="https://github.com/click6067-ship-it/token-tv/tree/main/examples/gameboy"><img src="https://raw.githubusercontent.com/click6067-ship-it/token-tv/main/examples/gameboy/comparison.png" width="640" alt="Change a face: original pixel style and a four-colour Game Boy example, rendered from the same sample readings"></a></p>

token_tv-0.2.0/README.md

@@ -0,0 +1,18 @@
+<h1 align="center">TokenTV</h1>
+<p align="center">
+  <a href="https://github.com/click6067-ship-it/token-tv/releases/latest"><img alt="Release" src="https://img.shields.io/github/v/release/click6067-ship-it/token-tv"></a>
+  <a href="https://github.com/click6067-ship-it/token-tv/blob/main/LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/license-MIT-blue"></a>
+  <a href="https://hackaday.com/2026/10/06/smalltv-hacking-with-surprisingly-little-fuss/"><img alt="Featured on Hackaday" src="https://img.shields.io/badge/featured%20on-Hackaday-1a1a1a"></a>
+  <a href="https://github.com/steipete/CodexBar#desk-display"><img alt="Listed in CodexBar" src="https://img.shields.io/badge/listed%20in-CodexBar-555555"></a>
+</p>
+
+<p align="center"><img src="https://raw.githubusercontent.com/click6067-ship-it/token-tv/main/docs/images/real-clock.jpg" alt="TokenTV on a real tiny desk clock"></p>
+<p align="center"><img src="https://raw.githubusercontent.com/click6067-ship-it/token-tv/main/docs/images/clock-faces.png" alt="Six clock faces (sample data)"></p>
+
+Your Claude and Codex usage limits on a ~$5 Wi-Fi desk clock. No firmware flashing.  
+**Try it:** [live demo](https://token-tv.vercel.app), `npx token-tv demo` or `uvx token-tv demo`, no clock or login needed.  
+**Set it up:** give this repo to your AI and say *"Set up TokenTV for me."* It follows [AGENTS.md](https://github.com/click6067-ship-it/token-tv/blob/main/AGENTS.md).  
+**Make your own face:** no clock needed, start from the [Game Boy example](https://github.com/click6067-ship-it/token-tv/tree/main/examples/gameboy) and ask your AI to change it. [Guide](https://github.com/click6067-ship-it/token-tv/blob/main/docs/clock-faces.md) · [Share it](https://github.com/click6067-ship-it/token-tv/issues/new?template=share_a_face.md)  
+Details: [how it works](https://github.com/click6067-ship-it/token-tv/blob/main/docs/stock-photo-display.md) · [setup](https://github.com/click6067-ship-it/token-tv/blob/main/docs/setup.md) · [compatible clocks](https://github.com/click6067-ship-it/token-tv/blob/main/docs/hardware-compatibility.md) · [CodexBar input](https://github.com/click6067-ship-it/token-tv/blob/main/docs/codexbar.md) · [Apple Watch](https://github.com/click6067-ship-it/token-tv/blob/main/docs/apple-watch.md) · [한국어](https://github.com/click6067-ship-it/token-tv/blob/main/README.ko.md)  
+
+<p align="center"><a href="https://github.com/click6067-ship-it/token-tv/tree/main/examples/gameboy"><img src="https://raw.githubusercontent.com/click6067-ship-it/token-tv/main/examples/gameboy/comparison.png" width="640" alt="Change a face: original pixel style and a four-colour Game Boy example, rendered from the same sample readings"></a></p>

token_tv-0.2.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "token-tv"
+version = "0.2.0"
+description = "Your AI usage limits on a $5 desk clock: Claude, Codex and Grok on a 240x240 Wi-Fi clock"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+dependencies = ["Pillow>=10.2,<13"]
+
+[project.urls]
+Homepage = "https://github.com/click6067-ship-it/token-tv"
+Demo = "https://token-tv.vercel.app"
+
+[project.scripts]
+token-tv = "token_tv.cli:main"
+
+[tool.setuptools]
+packages = ["token_tv", "token_tv.providers", "token_tv.web", "token_tv.assets"]
+
+[tool.setuptools.package-data]
+"token_tv.web" = ["*"]
+"token_tv.assets" = ["*.png", "*.json"]

token_tv-0.2.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

token_tv-0.2.0/tests/test_app.py

@@ -0,0 +1,41 @@
+import json
+import threading
+import unittest
+from urllib.request import urlopen
+
+from http.server import ThreadingHTTPServer
+
+from token_tv.app import MOCK_ACCOUNTS, make_handler
+from token_tv.providers.mock import MockProvider
+
+
+class SnapshotTests(unittest.TestCase):
+    def test_snapshot_exposes_distinct_aliases_as_theme_paths(self):
+        server = ThreadingHTTPServer(("127.0.0.1", 0), make_handler(MOCK_ACCOUNTS, {
+            "claude": MockProvider(),
+            "codex": MockProvider(),
+        }))
+        thread = threading.Thread(target=server.serve_forever)
+        thread.start()
+        try:
+            with urlopen(f"http://127.0.0.1:{server.server_port}/snapshot") as response:
+                payload = response.read()
+                self.assertLessEqual(len(payload), 2048)
+                self.assertEqual(response.headers["Content-Type"], "application/json; charset=utf-8")
+            data = json.loads(payload)
+            self.assertEqual(data["schema"], 1)
+            self.assertEqual(set(data["accounts"]), {"claude_personal", "claude_work", "codex_personal"})
+            self.assertEqual(data["accounts"]["claude_work"]["alias"], "Claude work")
+            self.assertEqual(data["accounts"]["claude_work"]["status"], "mock")
+            with urlopen(f"http://127.0.0.1:{server.server_port}/snapshot/claude_work") as response:
+                account = json.load(response)
+            self.assertEqual(account["session_percent"], 61)
+            self.assertEqual(account["alias"], "Claude work")
+        finally:
+            server.shutdown()
+            server.server_close()
+            thread.join()
+
+
+if __name__ == "__main__":
+    unittest.main()

token_tv-0.2.0/tests/test_catalog.py

@@ -0,0 +1,194 @@
+import importlib.util
+import json
+import tempfile
+import unittest
+from pathlib import Path
+
+from token_tv import __version__, catalog
+from token_tv.display import STYLES
+
+ROOT = Path(__file__).resolve().parents[1]
+spec = importlib.util.spec_from_file_location('update_theme_votes', ROOT / 'scripts' / 'update_theme_votes.py')
+updater = importlib.util.module_from_spec(spec)
+spec.loader.exec_module(updater)
+
+
+def entry(id, added, issue=None, min_version='0.1.0', **extra):
+    return dict({'id': id, 'name': id.title(), 'author': 'tester', 'added_at': added, 'min_version': min_version,
+                 'source_url': 'https://github.com/example/token-tv', 'license': 'MIT', 'like_issue': issue}, **extra)
+
+
+CATALOG = {'schema_version': 1, 'themes': [
+    entry('digital', '2026-10-01T00:00:00Z', issue=11),
+    entry('neon', '2026-10-02T00:00:00Z', issue=12),
+    entry('retro', '2026-10-03T00:00:00Z', issue=13),
+    entry('hud', '2026-10-02T00:00:00Z', issue=14),
+    entry('pixel', '2026-09-01T00:00:00Z'),
+]}
+OLD = '2026-10-01T09:00:00Z'
+VOTES = {'schema_version': 1, 'last_attempt_at': '2026-10-03T12:00:00Z', 'counts': {
+    '11': {'count': 8, 'status': 'fresh', 'fetched_at': '2026-10-03T12:00:00Z'},
+    '12': {'count': 0, 'status': 'fresh', 'fetched_at': '2026-10-03T12:00:00Z'},
+    '14': {'count': 8, 'status': 'stale', 'fetched_at': OLD},
+}}
+
+
+def listed(installed=('pixel', 'digital', 'neon', 'retro', 'hud', 'space'), cat=CATALOG, votes=VOTES, version='0.1.0'):
+    return catalog.theme_list(installed=installed, catalog=cat, votes=votes, version=version)
+
+
+class CatalogTest(unittest.TestCase):
+    def ids(self, data, mode):
+        return [t['id'] for t in catalog.sort_themes(data['themes'], mode)]
+
+    def test_popular_and_new_order(self):
+        data = listed()
+        # counted (8, 8 stale, 0) first; then never-counted and Local, newest first.
+        self.assertEqual(self.ids(data, 'popular'), ['hud', 'digital', 'neon', 'retro', 'pixel', 'space'])
+        self.assertEqual(self.ids(data, 'new'), ['retro', 'hud', 'neon', 'digital', 'pixel', 'space'])
+
+    def test_ties_break_by_newest_then_id(self):
+        cat = {'schema_version': 1, 'themes': [entry('neon', '2026-10-02T00:00:00Z', 1), entry('hud', '2026-10-02T00:00:00Z', 2)]}
+        stamp = '2026-10-03T00:00:00Z'
+        votes = {'schema_version': 1, 'last_attempt_at': stamp, 'counts': {
+            '1': {'count': 3, 'status': 'fresh', 'fetched_at': stamp}, '2': {'count': 3, 'status': 'fresh', 'fetched_at': stamp}}}
+        data = listed(installed=('neon', 'hud'), cat=cat, votes=votes)
+        self.assertEqual(self.ids(data, 'popular'), ['hud', 'neon'])
+        self.assertEqual(self.ids(data, 'new'), ['hud', 'neon'])
+
+    def test_unknown_likes_are_not_zero(self):
+        themes = {t['id']: t for t in listed()['themes']}
+        self.assertEqual((themes['retro']['likes'], themes['retro']['likes_state']), (None, 'unavailable'))
+        self.assertEqual((themes['pixel']['likes'], themes['pixel']['likes_state']), (None, 'not_open'))
+        self.assertIsNone(themes['pixel']['like_url'])
+        self.assertEqual((themes['hud']['likes'], themes['hud']['likes_state']), (8, 'stale'))
+        self.assertEqual(themes['hud']['likes_counted_at'], OLD)  # an old count keeps its own time
+
+    def test_zero_likes_stay_zero(self):
+        neon = next(t for t in listed()['themes'] if t['id'] == 'neon')
+        self.assertEqual((neon['likes'], neon['likes_state']), (0, 'counted'))
+        self.assertTrue(neon['like_url'].endswith('/issues/12'))
+
+    def test_blank_snapshot_is_still_useful(self):
+        data = listed(votes=catalog.BLANK_VOTES)
+        self.assertIsNone(data['last_attempt_at'])
+        self.assertEqual(len(data['themes']), 6)
+        self.assertTrue(all(t['likes'] is None for t in data['themes']))
+        self.assertEqual(self.ids(data, 'popular'), self.ids(data, 'new'))
+
+    def test_local_face_without_catalog_entry_is_listed_as_local(self):
+        space = next(t for t in listed()['themes'] if t['id'] == 'space')
+        self.assertTrue(space['local'] and space['installed'])
+        self.assertEqual(space['likes_state'], 'local')
+        self.assertFalse(space['needs_update'])
+
+    def test_newer_theme_needs_update_and_is_not_installed(self):
+        cat = {'schema_version': 1, 'themes': CATALOG['themes'] + [entry('vapor', '2026-10-04T00:00:00Z', min_version='0.3.0')]}
+        vapor = next(t for t in listed(cat=cat)['themes'] if t['id'] == 'vapor')
+        self.assertEqual((vapor['installed'], vapor['needs_update']), (False, True))
+        self.assertEqual(vapor['min_version'], '0.3.0')
+
+    def test_version_compare(self):
+        self.assertTrue(catalog.version_at_least('0.10.0', '0.9.1'))
+        self.assertFalse(catalog.version_at_least('0.1.0', '0.2.0'))
+        self.assertTrue(catalog.version_at_least('1.0', '1.0.0'))
+
+    def test_bad_catalog_is_rejected(self):
+        for broken in ({'schema_version': 2, 'themes': []},
+                       {'schema_version': 1, 'themes': [entry('digital', 'x'), entry('digital', 'x')]},
+                       {'schema_version': 1, 'themes': [dict(entry('digital', '2026-10-01T00:00:00Z'), like_issue='12')]},
+                       {'schema_version': 1, 'themes': [dict(entry('Bad Id', '2026-10-01T00:00:00Z'))]},
+                       {'schema_version': 1, 'themes': [dict(entry('digital', '2026-10-01T00:00:00Z'), source_url='javascript:x')]}):
+            with self.assertRaises(ValueError):
+                catalog.validate_catalog(broken)
+
+    def test_corrupt_vote_file_means_unavailable_not_zero(self):
+        path = Path(tempfile.mkdtemp()) / 'votes.json'
+        path.write_text('{"counts": ')
+        votes = catalog.load_votes(path)
+        self.assertEqual(votes['counts'], {})
+        self.assertIsNone(votes['last_attempt_at'])
+
+    def test_bad_or_missing_count_times_are_unknown_not_new(self):
+        path = Path(tempfile.mkdtemp()) / 'votes.json'
+        path.write_text(json.dumps({'last_attempt_at': 'yesterday', 'counts': {
+            '11': {'count': 5, 'status': 'fresh', 'fetched_at': 'not a time'},  # unreadable -> unavailable
+            '12': {'count': 5, 'status': 'fresh'},                              # fresh without time -> unavailable
+            '14': {'count': 7, 'status': 'stale'}}}))                           # old count, time unknown
+        votes = catalog.load_votes(path)
+        self.assertIsNone(votes['last_attempt_at'])
+        themes = {t['id']: t for t in listed(votes=votes)['themes']}
+        self.assertEqual([themes[i]['likes_state'] for i in ('digital', 'neon')], ['unavailable', 'unavailable'])
+        self.assertIsNone(themes['digital']['likes'])
+        self.assertEqual((themes['hud']['likes'], themes['hud']['likes_state'], themes['hud']['likes_counted_at']),
+                         (7, 'stale', None))
+
+    def test_installed_face_needing_newer_version_cannot_be_picked_from_catalog(self):
+        cat = {'schema_version': 1, 'themes': [entry('neon', '2026-10-02T00:00:00Z', min_version='0.2.0')]}
+        neon = next(t for t in listed(installed=('neon', 'mine'), cat=cat)['themes'] if t['id'] == 'neon')
+        self.assertEqual((neon['installed'], neon['needs_update']), (True, True))
+        mine = next(t for t in listed(installed=('neon', 'mine'), cat=cat)['themes'] if t['id'] == 'mine')
+        self.assertEqual((mine['local'], mine['needs_update']), (True, False))
+
+    def test_bundled_catalog_matches_installed_faces(self):
+        data = catalog.validate_catalog(json.loads(catalog.CATALOG_PATH.read_text()))
+        self.assertLessEqual({t['id'] for t in data['themes']}, set(STYLES))  # a fork may add Local faces
+        # Existing public issues stay mapped; new faces have no voting issue yet.
+        self.assertEqual({t['id']: t['like_issue'] for t in data['themes']},
+                         {'pixel': 1, 'digital': 2, 'neon': 3, 'retro': 4, 'hud': 5, 'space': 6, 'gameboy': None})
+        votes = catalog.load_votes()
+        self.assertTrue(set(votes['counts']) <= {str(t['like_issue']) for t in data['themes']})
+        self.assertTrue(all(v['fetched_at'] for v in votes['counts'].values()))  # every count is dated
+
+    def test_broken_bundled_catalog_still_lists_installed_faces(self):
+        from unittest import mock
+        with mock.patch.object(catalog, 'CATALOG_PATH', Path(tempfile.mkdtemp()) / 'missing.json'):
+            data = catalog.payload()
+        self.assertTrue(data['catalog_error'])
+        self.assertEqual({t['id'] for t in data['themes'] if t['local']}, set(STYLES))
+
+    def test_package_version_matches_pyproject(self):
+        self.assertIn(f'version = "{__version__}"', (ROOT / 'pyproject.toml').read_text())
+
+
+class RefreshTest(unittest.TestCase):
+    def test_refresh_keeps_last_count_on_failure(self):
+        def fetch(issue):
+            if issue == 11:
+                return 9
+            raise OSError('timeout')
+        now = '2026-10-04T00:00:00Z'
+        out = updater.refresh(CATALOG, VOTES, fetch, now=now)
+        self.assertEqual(out['counts']['11'], {'count': 9, 'status': 'fresh', 'fetched_at': now})
+        # kept, marked stale, and still dated when it was really counted
+        self.assertEqual(out['counts']['12'], {'count': 0, 'status': 'stale', 'fetched_at': '2026-10-03T12:00:00Z'})
+        self.assertEqual(out['counts']['14']['fetched_at'], OLD)
+        self.assertNotIn('13', out['counts'])  # never counted stays unknown, not 0
+        self.assertEqual(out['last_attempt_at'], now)
+        themes = {t['id']: t for t in listed(votes=out)['themes']}
+        self.assertEqual((themes['neon']['likes_state'], themes['neon']['likes_counted_at']), ('stale', '2026-10-03T12:00:00Z'))
+
+    def test_refresh_without_issue_skips_network(self):
+        calls = []
+        cat = {'schema_version': 1, 'themes': [entry('pixel', '2026-09-01T00:00:00Z')]}
+        out = updater.refresh(cat, catalog.BLANK_VOTES, lambda n: calls.append(n), now='2026-10-04T00:00:00Z')
+        self.assertEqual((calls, out['counts']), ([], {}))
+
+    def test_refresh_counts_issue_body_thumbs_only(self):
+        payload = {'reactions': {'+1': 4, 'heart': 9, 'total_count': 13}, 'comments': 7}
+        self.assertEqual(updater.thumbs_up(payload), 4)
+        for bad in ({}, {'reactions': {'+1': -1}}, {'reactions': {'+1': '4'}}, [], {'reactions': None}):
+            with self.assertRaises(ValueError):
+                updater.thumbs_up(bad)
+
+    def test_all_failures_keep_every_count_time(self):
+        def fail(issue):
+            raise ValueError('bad json')
+        out = updater.refresh(CATALOG, VOTES, fail, now='2026-10-04T00:00:00Z')
+        self.assertTrue(all(v['status'] == 'stale' for v in out['counts'].values()))
+        self.assertEqual({k: v['fetched_at'] for k, v in out['counts'].items()},
+                         {k: v['fetched_at'] for k, v in VOTES['counts'].items()})
+
+
+if __name__ == '__main__':
+    unittest.main()

token_tv-0.2.0/tests/test_cli.py

@@ -0,0 +1,280 @@
+import contextlib
+import io
+import json
+import os
+import tempfile
+import unittest
+from pathlib import Path
+from unittest import mock
+
+from token_tv import cli, sources
+from token_tv.display import STYLES
+
+
+def run(*argv):
+    out, err = io.StringIO(), io.StringIO()
+    with contextlib.redirect_stdout(out), contextlib.redirect_stderr(err):
+        code = cli.main(list(argv))
+    return code, out.getvalue(), err.getvalue()
+
+
+class CliTest(unittest.TestCase):
+    def setUp(self):
+        self.tmp = Path(tempfile.mkdtemp())
+        self.config = self.tmp / 'config.json'
+
+    def test_setup_writes_metadata_only_and_never_overwrites(self):
+        code, out, _ = run('setup', '--config', str(self.config), '--yes',
+                           '--claude-email', 'a@example.com', '--device-url', 'http://10.0.0.9/')
+        self.assertEqual(code, 0)
+        data = json.loads(self.config.read_text())
+        self.assertEqual(data['device_url'], 'http://10.0.0.9')
+        self.assertEqual(data['accounts'][0], {'key': 'claude_a', 'alias': 'CLAUDE A', 'provider': 'claude',
+                                               'email': 'a@example.com', 'source_home': '~/.claude'})
+        sources.load_config(self.config)  # the daemon accepts what setup writes
+        before = self.config.read_text()
+        code, _, err = run('setup', '--config', str(self.config), '--yes', '--codex-email', 'b@example.com')
+        self.assertEqual(code, 1)
+        self.assertIn('never overwrites', err)
+        self.assertEqual(self.config.read_text(), before)
+
+    def test_setup_without_accounts_fails_and_writes_nothing(self):
+        code, _, err = run('setup', '--config', str(self.config), '--yes')
+        self.assertEqual(code, 1)
+        self.assertFalse(self.config.exists())
+        self.assertIn('--claude-email', err)
+
+    def test_doctor_points_missing_logins_at_connect(self):
+        home = self.tmp / 'codex-home'
+        self.config.write_text(json.dumps({'accounts': [
+            {'key': 'codex_a', 'alias': 'CODEX A', 'provider': 'codex', 'email': 'b@example.com',
+             'source_home': str(home)}]}))
+        with mock.patch.object(cli, 'cli_path', return_value='/usr/bin/codex'):
+            code, out, _ = run('doctor', '--config', str(self.config))
+            self.assertEqual(code, 1)
+            self.assertIn('token-tv connect --config', out)
+            home.mkdir()
+            (home / 'auth.json').write_text('{}')  # existence only; doctor never opens it
+            code, out, _ = run('doctor', '--config', str(self.config))
+        self.assertEqual(code, 0)
+        self.assertIn('not verified', out)
+        self.assertNotIn('Ready', out)
+        bad = {'status': 'identity_mismatch', 'identity_verified': False}
+        with mock.patch.object(cli, 'cli_path', return_value='/usr/bin/codex'), \
+                mock.patch('token_tv.sources.fetch_account', return_value=bad):
+            code, out, _ = run('doctor', '--config', str(self.config), '--live')
+        self.assertEqual(code, 1)
+        self.assertIn('IDENTITY_MISMATCH', out)
+        good = {'status': 'ok', 'identity_verified': True}
+        with mock.patch.object(cli, 'cli_path', return_value='/usr/bin/codex'), \
+                mock.patch('token_tv.sources.fetch_account', return_value=good):
+            code, out, _ = run('doctor', '--config', str(self.config), '--live')
+        self.assertEqual(code, 0)
+        self.assertIn('Ready', out)
+
+    def test_doctor_never_calls_an_unchecked_keychain_ready(self):
+        self.config.write_text(json.dumps({'accounts': [
+            {'key': 'claude_a', 'alias': 'CLAUDE A', 'provider': 'claude', 'email': 'a@example.com',
+             'source_home': str(self.tmp / 'empty')}]}))
+        with mock.patch.object(cli, 'cli_path', return_value='/usr/bin/claude'), \
+                mock.patch.object(cli.sys, 'platform', 'darwin'):
+            code, out, _ = run('doctor', '--config', str(self.config))
+        self.assertEqual(code, 1)
+        self.assertIn('Keychain unchecked', out)
+
+    def test_doctor_checks_codexbar_instead_of_a_login_file(self):
+        self.config.write_text(json.dumps({'accounts': [
+            {'key': 'claude_a', 'alias': 'CLAUDE A', 'provider': 'claude', 'email': 'a@example.com',
+             'codexbar_command': str(self.tmp / 'missing-codexbar'), 'codexbar_source': 'oauth'}]}))
+        code, out, _ = run('doctor', '--config', str(self.config))
+        self.assertEqual(code, 1)
+        self.assertIn('install the CodexBar CLI', out)
+        self.assertNotIn('token-tv connect', out)
+        unreported = {'status': 'ok', 'identity_verified': False}
+        with mock.patch('token_tv.sources.fetch_account', return_value=unreported):
+            code, out, _ = run('doctor', '--config', str(self.config), '--live')
+        self.assertEqual(code, 0)
+        self.assertIn('CodexBar did not report the email for CLAUDE A', out)
+        failed = {'status': 'error', 'identity_verified': False}
+        with mock.patch('token_tv.sources.fetch_account', return_value=failed):
+            code, out, _ = run('doctor', '--config', str(self.config), '--live')
+        self.assertEqual(code, 1)
+        self.assertIn('live check ERROR', out)
+
+    def test_broken_config_gets_a_sentence_not_a_traceback(self):
+        self.config.write_text('{"accounts": [')
+        for command in ('doctor', 'run'):
+            code, _, err = run(command, '--config', str(self.config))
+            self.assertEqual(code, 1)
+            self.assertIn('not a valid TokenTV config', err)
+
+    def test_setup_two_accounts_reuse_then_isolate(self):
+        code, out, _ = run('setup', '--config', str(self.config), '--yes',
+                           '--codex-email', 'a@example.com', '--codex-email', 'b@example.com')
+        self.assertEqual(code, 0)
+        a, b = json.loads(self.config.read_text())['accounts']
+        self.assertEqual((a['key'], a['source_home']), ('codex_a', '~/.codex'))
+        self.assertEqual((b['key'], b['alias'], b['source_home']),
+                         ('codex_b', 'CODEX B', str(self.tmp / 'homes' / 'codex_b')))
+        self.assertIn('separate login', out)
+        sources.load_config(self.config)
+
+    def test_setup_isolate_never_points_at_the_everyday_home(self):
+        run('setup', '--config', str(self.config), '--yes', '--isolate', '--claude-email', 'a@example.com')
+        self.assertNotEqual(json.loads(self.config.read_text())['accounts'][0]['source_home'], '~/.claude')
+
+    def test_bad_clock_address_is_rejected_before_writing(self):
+        for bad in ('192.168.0.50', 'ftp://clock', 'http://', 'http://clock/photo', 'http://clock:99999'):
+            code, _, err = run('setup', '--config', str(self.config), '--yes',
+                               '--claude-email', 'a@example.com', '--device-url', bad)
+            self.assertEqual(code, 1, bad)
+            self.assertFalse(self.config.exists())
+        self.assertEqual(cli.device_address('http://10.0.0.9:8080/'), 'http://10.0.0.9:8080')
+
+    def test_doctor_without_config_explains_setup(self):
+        code, _, err = run('doctor', '--config', str(self.config))
+        self.assertEqual(code, 1)
+        self.assertIn('token-tv setup', err)
+
+    def test_demo_renders_every_face_from_sample_data(self):
+        code, out, _ = run('demo', '--out', str(self.tmp / 'demo'), '--scale', '2')
+        self.assertEqual(code, 0)
+        files = list((self.tmp / 'demo').iterdir())
+        self.assertEqual(len([p for p in files if '@' not in p.name]), len(STYLES))
+        self.assertIn('demo-space.gif', [p.name for p in files])
+        signature = {'.jpg': b'\xff\xd8\xff', '.gif': b'GIF8', '.png': b'\x89PNG'}
+        for path in files:  # every extension matches the bytes inside
+            self.assertTrue(path.read_bytes().startswith(signature[path.suffix]), path.name)
+        self.assertIn('Sample data only', out)
+
+
+class KeychainTest(unittest.TestCase):
+    def test_service_names_follow_claude_code(self):
+        root = Path('/Users/me/.token-tv/claude-b')
+        self.assertEqual(sources.keychain_services(root), ['Claude Code-credentials-' + __import__('hashlib')
+                                                           .sha256(str(root).encode()).hexdigest()[:8]])
+        default = Path('~/.claude').expanduser()
+        self.assertEqual(sources.keychain_services(default)[-1], 'Claude Code-credentials')
+
+    def test_keychain_is_used_only_on_macos_without_a_file(self):
+        root = Path(tempfile.mkdtemp())
+        with mock.patch.object(sources.sys, 'platform', 'linux'):
+            with self.assertRaises(FileNotFoundError):
+                sources.claude_token(root)
+        found = mock.Mock(returncode=0, stdout=json.dumps({'claudeAiOauth': {'accessToken': 'synthetic'}}))
+        with mock.patch.object(sources.sys, 'platform', 'darwin'), \
+                mock.patch.object(sources.subprocess, 'run', return_value=found) as call, \
+                mock.patch.dict(os.environ, {'USER': 'me'}):
+            self.assertEqual(sources.claude_token(root), 'synthetic')
+        self.assertEqual(call.call_args[0][0][:5], ['security', 'find-generic-password', '-a', 'me', '-w'])
+        missing = mock.Mock(returncode=44, stdout='')
+        with mock.patch.object(sources.sys, 'platform', 'darwin'), \
+                mock.patch.object(sources.subprocess, 'run', return_value=missing):
+            with self.assertRaises(sources.SourceError):
+                sources.claude_token(root)
+
+
+if __name__ == '__main__':
+    unittest.main()
+
+
+class ConnectGuardTest(unittest.TestCase):
+    def test_everyday_login_is_kept_without_explicit_replace(self):
+        from token_tv import connect
+        home = Path(tempfile.mkdtemp())
+        (home / '.codex').mkdir()
+        (home / '.codex' / 'auth.json').write_text('{}')
+        config = home / 'config.json'
+        config.write_text(json.dumps({'accounts': [{'key': 'codex_a', 'alias': 'CODEX A', 'provider': 'codex',
+                                                     'email': 'a@example.com', 'source_home': '~/.codex'}]}))
+        with mock.patch.dict(os.environ, {'HOME': str(home)}), \
+                mock.patch.object(connect.subprocess, 'run') as login, \
+                mock.patch.object(connect.sys, 'argv', ['connect', '--config', str(config), '--account', 'codex_a']):
+            out = io.StringIO()
+            with contextlib.redirect_stdout(out):
+                connect.main()
+        login.assert_not_called()
+        self.assertIn('Kept the existing login', out.getvalue())
+
+    def test_macos_keychain_login_is_protected_without_a_file(self):
+        from token_tv import connect
+        home = Path(tempfile.mkdtemp())  # no ~/.claude/.credentials.json at all
+        config = home / 'config.json'
+        config.write_text(json.dumps({'accounts': [{'key': 'claude_a', 'alias': 'CLAUDE A', 'provider': 'claude',
+                                                     'email': 'a@example.com', 'source_home': '~/.claude'}]}))
+        with mock.patch.dict(os.environ, {'HOME': str(home)}), \
+                mock.patch.object(connect.sys, 'platform', 'darwin'), \
+                mock.patch.object(connect.subprocess, 'run') as login, \
+                mock.patch.object(connect.sys, 'argv', ['connect', '--config', str(config), '--account', 'claude_a']):
+            out = io.StringIO()
+            with contextlib.redirect_stdout(out):
+                connect.main()
+        login.assert_not_called()
+        self.assertIn('Keychain', out.getvalue())
+
+
+class StartTest(unittest.TestCase):
+    def setUp(self):
+        self.config = Path(tempfile.mkdtemp()) / 'config.json'
+
+    def start(self, *extra):
+        from token_tv import live
+        with mock.patch.object(cli, 'cli_path', return_value='/usr/bin/x'), \
+                mock.patch.object(cli, 'login_state', side_effect=lambda p, h: 'yes' if p != 'grok' else 'no'), \
+                mock.patch('token_tv.sources.logged_in_email',
+                           side_effect=lambda p, h: {'claude': 'me@example.com', 'codex': None}[p]) as detect, \
+                mock.patch.object(live, 'main') as run:
+            code, out, err = run_cli('start', '--config', str(self.config), '--yes', '--no-browser', *extra)
+        return code, out, err, detect, run
+
+    def test_detects_signed_in_email_and_runs(self):
+        code, out, _, detect, run = self.start('--device-url', '192.168.0.50')
+        self.assertEqual(code, 0)
+        data = json.loads(self.config.read_text())
+        self.assertEqual([(a['provider'], a['email']) for a in data['accounts']], [('claude', 'me@example.com')])
+        self.assertEqual(data['device_url'], 'http://192.168.0.50')  # bare IP is accepted
+        run.assert_called_once()
+
+    def test_existing_config_skips_detection(self):
+        self.config.write_text(json.dumps({'accounts': [{'key': 'codex_a', 'alias': 'CODEX A', 'provider': 'codex',
+                                                         'email': 'b@example.com', 'source_home': '~/.codex'}]}))
+        code, _, _, detect, run = self.start()
+        self.assertEqual(code, 0)
+        detect.assert_not_called()
+        run.assert_called_once()
+
+    def saved_config(self, device_url):
+        config = {'device_url': device_url, 'accounts': [{'key': 'codex_a', 'alias': 'CODEX A', 'provider': 'codex',
+                                                          'email': 'b@example.com', 'source_home': '~/.codex'}]}
+        self.config.write_text(json.dumps(config))
+        return config
+
+    def test_new_clock_address_with_existing_config_stops_and_says_where(self):
+        # Reported in #7: the clock's IP changed and --device-url was silently ignored.
+        saved = self.saved_config('http://192.168.0.50')
+        code, _, err, _, run = self.start('--device-url', '192.168.0.77')
+        self.assertEqual(code, 1)
+        self.assertIn('http://192.168.0.50', err)
+        self.assertIn('http://192.168.0.77', err)
+        self.assertIn(str(self.config), err)
+        self.assertEqual(json.loads(self.config.read_text()), saved)
+        run.assert_not_called()
+
+    def test_same_clock_address_with_existing_config_runs(self):
+        self.saved_config('http://192.168.0.50')
+        code, _, err, _, run = self.start('--device-url', '192.168.0.50')
+        self.assertEqual((code, err), (0, ''))
+        run.assert_called_once()
+
+    def test_nothing_signed_in_explains_next_step(self):
+        from token_tv import live
+        with mock.patch.object(cli, 'cli_path', return_value=None), mock.patch.object(live, 'main') as run:
+            code, _, err = run_cli('start', '--config', str(self.config), '--yes', '--no-browser')
+        self.assertEqual(code, 1)
+        self.assertIn('token-tv demo', err)
+        self.assertFalse(self.config.exists())
+        run.assert_not_called()
+
+
+def run_cli(*argv):
+    return run(*argv)