{"id":13927058,"url":"https://github.com/luk400/vim-lichess","last_synced_at":"2025-03-26T22:30:56.814Z","repository":{"id":59714596,"uuid":"529706127","full_name":"luk400/vim-lichess","owner":"luk400","description":"Play lichess in (neo)vim!","archived":false,"fork":false,"pushed_at":"2023-02-03T09:22:11.000Z","size":48,"stargazers_count":110,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-22T14:22:26.091Z","etag":null,"topics":["chess","lichess","neovim","neovim-plugin","online-chess","terminal-based","vim","vim-plugin"],"latest_commit_sha":null,"homepage":"","language":"Vim Script","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/luk400.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2022-08-27T22:01:54.000Z","updated_at":"2025-03-11T07:44:55.000Z","dependencies_parsed_at":"2023-02-18T05:15:52.176Z","dependency_job_id":null,"html_url":"https://github.com/luk400/vim-lichess","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luk400%2Fvim-lichess","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luk400%2Fvim-lichess/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luk400%2Fvim-lichess/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/luk400%2Fvim-lichess/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/luk400","download_url":"https://codeload.github.com/luk400/vim-lichess/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":245747509,"owners_count":20665802,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["chess","lichess","neovim","neovim-plugin","online-chess","terminal-based","vim","vim-plugin"],"created_at":"2024-08-07T16:01:22.153Z","updated_at":"2025-03-26T22:30:56.475Z","avatar_url":"https://github.com/luk400.png","language":"Vim Script","funding_links":[],"categories":["Vim Script"],"sub_categories":[],"readme":"# vim-lichess\n\nPlay online chess in (Neo)Vim!\n\n![vimlichessdemo](https://user-images.githubusercontent.com/57172028/190704946-4708be17-83c0-4652-ae3e-9cb958faa557.gif)\n\n### Why?\n\nBecause why not. Not having to leave (Neo)Vim to play online chess should be a basic human right.\n\n### Honestly, why?\n\nHonestly, because why not.\n\n## Requirements\n\n* (Neo)Vim with python3 support\n* `berserk` package for python3 (install via `pip install berserk`) - note in case you have the package simplejson installed: berserk seems to be incompatible with simplejson, see [this comment for a possible workaround](https://github.com/luk400/vim-lichess/issues/2#issuecomment-1250392384)\n* A lichess account\n\n## Basic setup and how to play\n\nInstall the plugin using e.g. `Plug 'luk400/vim-lichess'` in case you're using vim-plug. \n\nOpen (Neo)Vim and run `:LichessFindGame`. You'll be prompted with instructions on how to create and specify your lichess API token in your vim config if you haven't yet (see first variable in section [Other parameters](#other-parameters)). If you've already set your API Token, a new buffer will open and a new game will be started. \n\n***You can then play by simply left-clicking on a piece and then right-clicking on its destination square***, or alternatively by typing the move in UCI format ([see this link for examples](https://en.wikipedia.org/wiki/Universal_Chess_Interface#Design)) after using the `LichessMakeMoveUCI` command.\n\nFor other actions, such as resigning, offering draws, takebacks, chatting, etc. see section [Commands and mappings](#commands-and-mappings)\n\nWhen the game is over, you can either start a new game again using `:LichessFindGame` or delete the buffer using e.g. `:bd` and get back to whatever you've been doing before.\n\n## Commands and mappings\n\n#### Commands\n* `:LichessFindGame`: Find a new game using [the parameters specified in your vim config](#game-parameters)\n* `:LichessResign`: Resign a game\n* `:LichessAbort`: Abort a game\n* `:LichessClaimVictory`: Claim victory if opponent has abandoned the game (unfortunately there's no way to determine whether a game is \"claimable\" through lichess API, thus you'll just have to try by running the command when you think the opponent might've abandoned the game)\n* `:LichessDrawOfferAccept`: Create or accept a draw offer\n* `:LichessDrawDecline`: Decline a draw offer\n* `:LichessTakebackOfferAccept`: Create or accept a takeback offer\n* `:LichessTakebackOfferDecline`: Decline a takeback offer\n* `:LichessMakeMoveUCI`: type a move to make in UCI format ([see this link for examples](https://en.wikipedia.org/wiki/Universal_Chess_Interface#Design))\n* `:LichessChat`: write a message in chat (note that your messages won't register if you're shadowbanned)\n\n#### Mappings\n```vim\nnnoremap \u003cbuffer\u003e \u003cleader\u003elm :LichessMakeMoveUCI\u003ccr\u003e\nnnoremap \u003cbuffer\u003e \u003cleader\u003elc :LichessChat \nnnoremap \u003cbuffer\u003e \u003cleader\u003ela :LichessAbort\u003ccr\u003e\nnnoremap \u003cbuffer\u003e \u003cleader\u003elr :LichessResign\u003ccr\u003e\nnnoremap \u003cbuffer\u003e \u003cleader\u003eldo :LichessOfferDraw\u003ccr\u003e\nnnoremap \u003cbuffer\u003e \u003cleader\u003elda :LichessAcceptDraw\u003ccr\u003e\nnnoremap \u003cbuffer\u003e \u003cleader\u003eldd :LichessDeclineDraw\u003ccr\u003e\nnnoremap \u003cleader\u003ech :call lichess#play#find_game()\u003ccr\u003e\n```\n\n## Global variables\n\n#### Game parameters\n```vim\nlet g:lichess_autoqueen = 1\n\" whether to automatically promote to queen or not\nlet g:lichess_time = 10\n\" game time in minutes - must be \u003e= 8, since lichess API only allows rapid or classical games\nlet g:lichess_increment = 0\n\" increment in seconds\nlet g:lichess_rated = 1\n\" whether to play rated games (1) or unrated games (0)\nlet g:lichess_variant = \"standard\"\n\" lichess variant to play -\u003e this plugin has currently only been tested with 'standard'! possible values: ['standard', 'chess960', 'crazyhouse', 'antichess', 'atomic', 'horde', 'kingOfTheHill', 'racingKings', 'threeCheck']\nlet g:lichess_color = \"random\"\n\" which color you want to play as. possible values: ['white', 'black', 'random']\nlet g:lichess_rating_range = []\n\" rating range of your opponents, can be an empty list to use the default (recommended) or a list like `[low,high]`, where `low` and `high` are integers.\n```\n\n#### Other parameters\n```vim\nlet g:lichess_api_token = ''\n\" your required lichess API token. you can easily easily create one which you can put in your config using this link: https://lichess.org/account/oauth/token/create?scopes[]=challenge:write\u0026scopes[]=board:play\u0026description=vim+lichess\nlet g:python_cmd = 'python3'\n\" python command to run server in background - this should be the python executable for which berserk is installed (can also be a full path)\nlet g:lichess_debug_level = -1\n\" set debugging level. -1 means nothing is logged and no log files are created, 0 -\u003e all info is logged, 1 -\u003e only warnings and 'worse' are logged, 2 -\u003e only errors and 'worse' are logged, 3 -\u003e only crashes are logged\n```\n\n#### Highlighting\n\nIn case you want change the board colors or other highlighting options, you can modify any of the following highlights and put them in your vim config (AFTER  the plugin is loaded - e.g. after `call plug#end()` in case you're using vim-plug) to overwrite them:\n\n```vim\nhighlight lichess_black_squares guibg=#B58863 ctermbg=94\n\" highlighting of black squares\nhighlight lichess_white_squares guibg=#F0D9B5 ctermbg=7\n\" highlighting of white squares\nhighlight lichess_black_pieces guifg=#000000 guibg=#000000 ctermbg=0 ctermfg=0\n\" highlighting of black pieces\nhighlight lichess_white_pieces guifg=#ffffff guibg=#ffffff ctermbg=15 ctermfg=15\n\" highlighting of white pieces\nhighlight lichess_from_square_dark guifg=#AAA23A guibg=#AAA23A ctermbg=172 ctermfg=172\n\" highlighting of the previous and new square of the latest moved piece if it's a dark square\nhighlight lichess_from_square_light guifg=#CDD26A guibg=#CDD26A ctermbg=178 ctermfg=178\n\" highlighting of the previous and new square of the latest moved piece if it's a light square\nhighlight lichess_cell_delimiters guifg=#000000 guibg=#000000 ctermbg=0 ctermfg=0\n\" highlighting of vertical cell delimiters between squares\nhighlight lichess_user_turn guibg=#3eed6c guifg=#000000 ctermbg=2 ctermfg=0 cterm=bold gui=bold\n\" highlighting of the name of the user whose turn it currently is\nhighlight lichess_user_noturn guifg=#ffffff ctermfg=15 cterm=bold gui=bold\n\" highlighting of the name of the user whose turn it's currently not\nhighlight lichess_searching_game guifg=#42d7f5 guibg=#000000 ctermfg=14 ctermbg=0 cterm=bold gui=bold\n\" highlighting of 'searching game...' prompt\nhighlight lichess_game_ended guibg=#e63c30 guifg=#ffffff ctermbg=1 ctermfg=15 cterm=bold gui=bold\n\" highlighting of last game status (e.g. 'MATE' or 'RESIGN')\nhighlight lichess_chat guibg=#e3f27e guifg=#000000 ctermbg=191 ctermfg=0\n\" highlighting of of opponent chat messages\nhighlight lichess_chat_system guibg=#ed8787 guifg=#000000 ctermbg=178 ctermfg=0\n\" highlighting of of lichess chat messages\nhighlight lichess_chat_you guibg=#b4e364 guifg=#000000 ctermbg=190 ctermfg=0\n\" highlighting of your chat messages\nhighlight lichess_chat_bold guibg=#e3f27e guifg=#000000 ctermbg=191 ctermfg=0 cterm=bold gui=bold\n\" highlighting of of 'CHAT:' prompt\nhighlight lichess_move_info guibg=#9ea832 guifg=#000000 ctermbg=3 ctermfg=0 cterm=bold gui=bold\n\" echohl highlighting of echoed move-message\nhighlight lichess_too_many_requests guibg=#c20202 guifg=#ffffff ctermbg=15 ctermfg=9 cterm=bold gui=bold\n\" echohl highlighting of too_many_requests error\n```\n\n#### Piece representation\n\nIn case you don't like my piece design, you can design your own as shown below.\nYou can also change their width/height (number of characters in strings/number of strings in list) to make them bigger if you want more detail, as long as you follow the following restrictions:\n* all pieces must have the same height (number of strings in piece list)\n* all pieces must have the same width (number of characters in the strings)\n* there must be exactly one unique non-whitespace character for all black and one unique non-whitespace character for all white pieces. This can not be the same for the white and black pieces and it must have a length of 1 (there are certain characters which have a different length in vim - e.g.: `echo len('║')` will print `3` even though it's a single character). Easiest way is just to use `,` for black and `;` for the white pieces, as shown below\n\n\n```vim\n\" black pieces\nlet g:lichess_piece_p =\n    \\   [\"            \",\n    \\    \"     ,,     \",\n    \\    \"    ,,,,    \",\n    \\    \"    ,,,,    \",\n    \\    \"    ,,,,    \",\n    \\    \"            \"] \" black pawn\nlet g:lichess_piece_r =\n    \\   [\"            \",\n    \\    \"   , ,, ,   \",\n    \\    \"   ,,,,,,   \",\n    \\    \"   ,,,,,,   \",\n    \\    \"  ,,,,,,,,  \",\n    \\    \"            \"] \" black rook\nlet g:lichess_piece_k =\n    \\   [\"            \",\n    \\    \"     ,,     \",\n    \\    \"  ,,,,,,,,  \",\n    \\    \"     ,,     \",\n    \\    \"     ,,     \",\n    \\    \"            \"] \" black king\nlet g:lichess_piece_q =\n    \\   [\"            \",\n    \\    \"   , ,, ,   \",\n    \\    \"    ,,,,    \",\n    \\    \"     ,,     \",\n    \\    \"   ,,,,,,   \",\n    \\    \"            \"] \" black queen\nlet g:lichess_piece_b =\n    \\   [\"            \",\n    \\    \"    ,,,,    \",\n    \\    \"    ,,,,    \",\n    \\    \"     ,,     \",\n    \\    \"   ,,,,,,   \",\n    \\    \"            \"] \" black bishop\nlet g:lichess_piece_n =\n    \\   [\"            \",\n    \\    \"    ,,,     \",\n    \\    \"  ,,, ,,    \",\n    \\    \"     ,,,    \",\n    \\    \"   ,,,,,,   \",\n    \\    \"            \"] \" black knight\n\n\" white pieces\nlet g:lichess_piece_P =\n    \\   [\"            \",\n    \\    \"     ;;     \",\n    \\    \"    ;;;;    \",\n    \\    \"    ;;;;    \",\n    \\    \"    ;;;;    \",\n    \\    \"            \"] \" white pawn\nlet g:lichess_piece_R =\n    \\   [\"            \",\n    \\    \"   ; ;; ;   \",\n    \\    \"   ;;;;;;   \",\n    \\    \"   ;;;;;;   \",\n    \\    \"  ;;;;;;;;  \",\n    \\    \"            \"] \" white rook\nlet g:lichess_piece_K =\n    \\   [\"            \",\n    \\    \"     ;;     \",\n    \\    \"  ;;;;;;;;  \",\n    \\    \"     ;;     \",\n    \\    \"     ;;     \",\n    \\    \"            \"] \" white king\nlet g:lichess_piece_Q =\n    \\   [\"            \",\n    \\    \"   ; ;; ;   \",\n    \\    \"    ;;;;    \",\n    \\    \"     ;;     \",\n    \\    \"   ;;;;;;   \",\n    \\    \"            \"] \" white queen\nlet g:lichess_piece_B =\n    \\   [\"            \",\n    \\    \"    ;;;;    \",\n    \\    \"    ;;;;    \",\n    \\    \"     ;;     \",\n    \\    \"   ;;;;;;   \",\n    \\    \"            \"] \" white bishop\nlet g:lichess_piece_N =\n    \\   [\"            \",\n    \\    \"    ;;;     \",\n    \\    \"  ;;; ;;    \",\n    \\    \"     ;;;    \",\n    \\    \"   ;;;;;;   \",\n    \\    \"            \"] \" white knight\n```\n\n# Credit\n\nAll credit goes to my huge procrastination issues\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluk400%2Fvim-lichess","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fluk400%2Fvim-lichess","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fluk400%2Fvim-lichess/lists"}